# cashflows

Compute cash flow for `FixedBond`, `FloatBond`, `Swap`, `FRA`, `STIRFuture`, `OISFuture`, `OvernightIndexedSwap`, or `Deposit` instrument

Since R2020a

## Syntax

``CF = cashflows(InstrumentObject,Settle)``

## Description

example

````CF = cashflows(InstrumentObject,Settle)` computes cash flow for a `Deposit`, `FRA`, ,`Swap`, `STIRFuture`, `OISFuture`, `FixedBond`, `OvernightIndexedSwap`, or `FloatBond` instrument object.```

## Examples

collapse all

This example shows the workflow to price a `FRA` (forward rate agreement) instrument and then use `cashflows` to determine the cash flow for the `FRA` instrument.

Create `FRA` Instrument Object

Use `fininstrument` to create a `FRA` instrument object.

`FRAObj = fininstrument("FRA",'StartDate',datetime(2020,9,15),'Maturity',datetime(2022,9,15),'Rate',0.175)`
```FRAObj = FRA with properties: Rate: 0.1750 Basis: 2 StartDate: 15-Sep-2020 Maturity: 15-Sep-2022 Principal: 100 BusinessDayConvention: "actual" Holidays: NaT 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

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

`outPricer = finpricer("Discount", 'DiscountCurve',myRC)`
```outPricer = Discount with properties: DiscountCurve: [1x1 ratecurve] ```

Price `FRA` Instrument

Use `price` to compute the price and sensitivities for the `FRA` instrument.

`[Price, outPR] = price(outPricer, FRAObj,["all"])`
```Price = 34.1757 ```
```outPR = priceresult with properties: Results: [1x2 table] PricerData: [] ```
`outPR.Results`
```ans=1×2 table Price DV01 ______ _______ 34.176 0.01368 ```

Use `cashflows` for the `FRA` instrument with a `Settle` date of `15-Dec-2021`. The specified `Settle` date must be before the instrument `Maturity` date.

`CF = cashflows(FRAObj,datetime(2021,12,15))`
```CF= 1×1timetable Time CFA ___________ ______ 15-Sep-2022 35.486 ```

This example shows the workflow to price an `OISFuture` instrument and then use `cashflows` to calculate the cashflow for the `OISFuture` instrument.

Create ratecurve Object

Create a `ratecurve` object using `ratecurve` for the underlying interest-rate curve for the `STIRFuture` instrument.

```Settle = datetime(2019,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-2019 InterpMethod: "linear" ShortExtrapMethod: "next" LongExtrapMethod: "previous" ```

Create `OISFuture` Instrument Object

Use `fininstrument` to create an `OISFuture` instrument object.

`OISFuture = fininstrument("OISFuture",'Maturity',datetime(2022,12,15),'QuotedPrice',99.5,'StartDate',datetime(2022,9,15),'Notional',90,'ProjectionCurve',myRC,'Name',"ois_future_instrument")`
```OISFuture = OISFuture with properties: QuotedPrice: 99.5000 Method: "compound" Basis: 2 StartDate: 15-Sep-2022 Maturity: 15-Dec-2022 Notional: 90 BusinessDayConvention: "actual" Holidays: NaT ProjectionCurve: [1x1 ratecurve] HistoricalFixing: [0x0 timetable] Name: "ois_future_instrument" ```

Create `Discount` Pricer Object

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

`outPricer = finpricer("Discount",'DiscountCurve',myRC)`
```outPricer = Discount with properties: DiscountCurve: [1x1 ratecurve] ```

Price `OISFuture` Instrument

Use `price` to compute the price and sensitivities for the `OISFuture` instrument.

`[Price, outPR] = price(outPricer,OISFuture,["all"])`
```Price = 2.6543 ```
```outPR = priceresult with properties: Results: [1x2 table] PricerData: [] ```
`outPR.Results`
```ans=1×2 table Price DV01 ______ __________ 2.6543 -0.0013589 ```

Use `cashflows` to calculate the cash flow for the `OISFuture` instrument with a `Settle` date of `15-Sep-2022`. The specified `Settle` date must be before the instrument `Maturity` date.

`CF = cashflows(OISFuture,datetime(2022,9,15))`
```CF= 1×1timetable Time CFA ___________ ______ 15-Dec-2022 2.7225 ```

This example shows the workflow to price multiple `FRA` (forward rate agreement) instruments and then use `cashflows` to determine the cash flow for each of the `FRA` instruments.

Create `FRA` Instrument Object

Use `fininstrument` to create a `FRA` instrument object for three FRA instruments.

`FRAObj = fininstrument("FRA",'StartDate',datetime([2020,9,15 ; 2020,10,15 ; 2020,11,15]),'Maturity',datetime([2022,9,15 ; 2022,10,15 ; 2022,11,15]),'Rate',0.175)`
```FRAObj=3×1 object 3x1 FRA array with properties: Rate Basis StartDate Maturity Principal BusinessDayConvention Holidays 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

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

`outPricer = finpricer("Discount", 'DiscountCurve',myRC)`
```outPricer = Discount with properties: DiscountCurve: [1x1 ratecurve] ```

Price `FRA` Instruments

Use `price` to compute the prices and sensitivities for the three `FRA` instrument.

`[Price, outPR] = price(outPricer, FRAObj,["all"])`
```Price = 3×1 34.1757 34.1207 34.0627 ```
```outPR=1×3 object 1x3 priceresult array with properties: Results PricerData ```
`outPR.Results`
```ans=1×2 table Price DV01 ______ _______ 34.176 0.01368 ```
```ans=1×2 table Price DV01 ______ ________ 34.121 0.013938 ```
```ans=1×2 table Price DV01 ______ ________ 34.063 0.014204 ```

Use `cashflows` for the three `FRA` instruments with a `Settle` date of April 15, 2022. The specified `Settle` date must be before the instrument `Maturity` date.

`CF = cashflows(FRAObj(1),datetime(2022,4,15))`
```CF= 1×1timetable Time CFA ___________ ______ 15-Sep-2022 35.486 ```
`CF = cashflows(FRAObj(2),datetime(2022,4,15))`
```CF= 1×1timetable Time CFA ___________ ______ 15-Oct-2022 35.486 ```
`CF = cashflows(FRAObj(3),datetime(2022,4,15))`
```CF= 1×1timetable Time CFA ___________ ______ 15-Nov-2022 35.486 ```

This example shows the workflow to price a `FixedBond` instrument and then use `cashflows` to calculate the cash flow for the `FixedBond` instrument.

Create `FixedBond` Instrument Object

Use `fininstrument` to create a `FixedBond` instrument object.

`FixB = fininstrument("FixedBond",'Maturity',datetime(2022,9,15),'CouponRate',0.05,'Period',4,'Basis',7,'Principal',1000,'BusinessDayConvention',"follow",'Name',"fixed_bond_instrument")`
```FixB = FixedBond with properties: CouponRate: 0.0500 Period: 4 Basis: 7 EndMonthRule: 1 Principal: 1000 DaycountAdjustedCashFlow: 0 BusinessDayConvention: "follow" Holidays: NaT IssueDate: NaT FirstCouponDate: NaT LastCouponDate: NaT StartDate: NaT Maturity: 15-Sep-2022 Name: "fixed_bond_instrument" ```

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

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

`outPricer = finpricer("Discount",'DiscountCurve',myRC)`
```outPricer = Discount with properties: DiscountCurve: [1x1 ratecurve] ```

Price `FixedBond` Instrument

Use `price` to compute the price and sensitivities for the `FixedBond` instrument.

`[Price, outPR] = price(outPricer, FixB,["all"])`
```Price = 1.1600e+03 ```
```outPR = priceresult with properties: Results: [1x2 table] PricerData: [] ```
`outPR.Results`
```ans=1×2 table Price DV01 _____ _______ 1160 0.42712 ```

Use `cashflows` to calculate the cash flow for the `FixedBond` instrument for any specified `Settle` date before the instrument `Maturity` date.

`CF = cashflows(FixB,datetime(2021,9,15))`
```CF=5×1 timetable Time Var1 ___________ ______ 15-Sep-2021 0 15-Dec-2021 12.5 15-Mar-2022 12.5 15-Jun-2022 12.5 15-Sep-2022 1012.5 ```

## Input Arguments

collapse all

Instrument object, specified using a previously created instrument object for one of the following: `Deposit`, `FixedBond`, `FloatBond`, `Swap`, `STIRFuture`, `OISFuture`, `OvernightIndexedSwap`, or `FRA`.

Note

If the `InstrumentObject` is a vector of instruments, you must use `cashflows` separately with each instrument.

Data Types: `object`

Settlement date for instrument cash flow, specified as a scalar datetime, string, or date character vector.

Note

The `Settle` date you specify must be before the `Maturity` date for the `Deposit`, `FixedBond`, `FloatBond`, `Swap`, `STIRFuture`, `OISFuture`,`OvernightIndexedSwap`, or `FRA` instrument.

To support existing code, `cashflows` also accepts serial date numbers as inputs, but they are not recommended.

## Output Arguments

collapse all

Cash flow, returned as a timetable.

## Version History

Introduced in R2020a

expand all