cfplot

Visualize cash flows of financial instruments

Syntax

cfplot(CFlowDates,CFlowAmounts)

cfplot(ax,CFlowDates,CFlowAmounts)

cfplot(___,Name,Value)

h = cfplot(___,Name,Value)

[h,axes_handle] = cfplot(___,Name,Value)

Description

cfplot(CFlowDates,CFlowAmounts) plots a cash flow diagram for the specified cash flow amounts (CFlowAmounts) and dates (CFlowDates). The length and orientation of each arrow correspond to the cash flow amount.

cfplot(ax,CFlowDates,CFlowAmounts) plots a cash flow diagram for the specified cash flow amounts using an optional ax argument.

cfplot(___,Name,Value) plots a cash flow diagram for the specified cash flow amounts (CFlowAmounts), dates (CFlowDates), and optional name-value pair arguments.

h = cfplot(___,Name,Value) returns the handle to the line objects used in the cash flow diagram.

[h,axes_handle] = cfplot(___,Name,Value) returns the handles to the line objects and the axes using optional name-value pair arguments.

Examples

Plot Cash Flows

Define CFlowAmounts and CFlowDates using the cfamounts function.

CouponRate = [0.06; 0.05; 0.03];
Settle = '03-Jun-1999';
Maturity = ['15-Aug-2000';'15-Dec-2000';'15-Jun-2000'];
Period = [1; 2; 2];  Basis = [1; 0; 0];
[CFlowAmounts, CFlowDates] = cfamounts(...
CouponRate, Settle, Maturity, Period, Basis)

CFlowAmounts = 3×5

   -4.8000    6.0000  106.0000       NaN       NaN
   -2.3352    2.5000    2.5000    2.5000  102.5000
   -1.4011    1.5000    1.5000  101.5000       NaN

CFlowDates = 3×5

      730274      730347      730713         NaN         NaN
      730274      730286      730469      730652      730835
      730274      730286      730469      730652         NaN

Plot all cash flows on the same axes, and label the first two.

cfplot(CFlowDates, CFlowAmounts, 'ShowAmnt', [1 2])

Group the second and third cash flows.

figure;
cfplot(CFlowDates, CFlowAmounts, 'Groups', {[2 3]}, 'ShowAmnt', 1);

Format the date axis and place ticks on actual cash flow dates.

figure;
cfplot(CFlowDates, CFlowAmounts, 'Groups', {[2 3]}, 'ShowAmnt', 1, ...
'DateFormat', 6, 'DateSpacing', 100);

Stack the cash flow arrows occurring on the same dates.

figure;
cfplot(CFlowDates, CFlowAmounts, 'Groups', {[2 3]}, 'ShowAmnt', 1, ...
'DateFormat', 6, 'DateSpacing', 100, 'Stacked', 1);

Form subplots of multiple groups and add titles using axes handles.

figure;
[h, axes_handle] = cfplot(CFlowDates, CFlowAmounts, ...
'Groups', {[1] [2 3]}, 'ShowAmnt', 1, 'Stacked', 2, ...
'DateSpacing', [1 60 2 100], 'DateFormat', [1 12 2 6]);
title(axes_handle(1), 'Group 1', 'FontWeight', 'bold');
title(axes_handle(2), 'Group 2', 'FontWeight', 'bold');

Plot Cash Flows Using datetime Input for CFlowDates

Define CFlowDates using datetime input and plot the cash flow.

CouponRate = [0.06; 0.05; 0.03];
Settle = '03-Jun-1999';
Maturity = ['15-Aug-2000';'15-Dec-2000';'15-Jun-2000'];
Period = [1; 2; 2];  Basis = [1; 0; 0];
[CFlowAmounts, CFlowDates] = cfamounts(...
CouponRate, Settle, Maturity, Period, Basis);
cfplot(datetime(CFlowDates,'ConvertFrom','datenum','Locale','en_US'), CFlowAmounts, 'ShowAmnt', [1 2])

Plot Cash Flows for Swap

Define the swap using the swapbyzero (Financial Instruments Toolbox) function.

Settle = datetime(2010,6,8);
RateSpec = intenvset('Rates', [.005 .0075 .01 .014 .02 .025 .03]',...
'StartDates',Settle, 'EndDates',[datetime(2010,12,8),datetime(2011,6,8),datetime(2012,6,8),datetime(2013,6,8),datetime(2015,6,8),datetime(2017,6,8),datetime(2020,6,8)]');
Maturity = datetime(2020,9,15);
LegRate = [.025 50];
LegType = [1 0]; % Fixed/Floating
LatestFloatingRate = .005;
[Price, SwapRate, AI, RecCF, RecCFDates, PayCF,PayCFDates] = ...
swapbyzero(RateSpec, LegRate, Settle, Maturity,'LegType',LegType,...
'LatestFloatingRate',LatestFloatingRate)

Price = 
-6.7258

SwapRate = 
NaN

AI = 
1.4575

RecCF = 1×12

   -1.8219    2.5000    2.5000    2.5000    2.5000    2.5000    2.5000    2.5000    2.5000    2.5000    2.5000  102.5000

RecCFDates = 1×12

      734297      734396      734761      735127      735492      735857      736222      736588      736953      737318      737683      738049

PayCF = 1×12

   -0.3644    0.5000    1.4048    1.9823    2.8436    3.2842    3.8218    4.1733    4.5164    4.4666    4.8068  104.6743

PayCFDates = 1×12

      734297      734396      734761      735127      735492      735857      736222      736588      736953      737318      737683      738049

Define CFlowDates and CFlowAmounts for the swap and generate a cash flow plot using cfplot.

CFlowDates = [PayCFDates;RecCFDates];
CFlowAmounts = [-PayCF;RecCF];
cfplot(CFlowDates, CFlowAmounts, 'Groups', {[1 2]});
xlabel('Numeric Cash Flow Dates');

Input Arguments

CFlowDates — Matrix of dates for cash flows

vector

Matrix of datetime arrays for cash flows, specified as a NINST-by-(Number of cash flows) matrix of cash flow dates using datetime format, with empty entries padded with NaNs.

Each row of the CFlowDates matrix represents an instrument so that CFlowDates(k,:) is the vector of cash flow dates for the kth instrument. Rows are padded with trailing NaNs if the number of cash flows is not the same for all instruments.

cfamounts can be used to generate CFlowDates.

Data Types: datetime

CFlowAmounts — Matrix of cash flow amounts

vector

Matrix of cash flow amounts, specified as a NINST-by-(Number of cash flows) matrix of cash flow amounts, with empty entries padded with NaNs. The CFlowAmounts matrix must be the same size as CFlowDates.

cfamounts can be used to generate CFlowAmounts.

Data Types: double

ax — Valid axis object

object

(Optional) Valid axis object, specified as an ax object that is created using axes. The plot will be created in the axes specified by the optional ax argument instead of in the current axes (gca). The optional argument ax can precede any of the input argument combinations.

Data Types: object

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: cfplot(CFlowDates,CFlowAmounts,'Groups',{[2 3]},'ShowAmnt',1,'DateFormat',6,'DateSpacing',100)

Groups — Group cash flows

'off' (default) | character vector with value 'off' or 'individual' | cell array of character vectors

Group cash flows, specified as the comma-separated pair consisting of 'Groups' and the following values:

• 'off' — Show all instruments in one set of axes, arranged from top to bottom.

• 'individual' — Generate subplots and plot each instrument in its own axis.

• GRP — Cell array of instrument groups, {Group1, Group2,... }. This generates subplots and plots each group in each axis. When specifying {Group1, Group2,... }, each Group must be mutually exclusive vectors of INSTIndex. Unspecified instruments are not shown in the grouped plot.

Data Types: char | cell

Stacked — Stack arrows if cash flows are in same direction on same day

ignored when 'Groups' is 'off', otherwise 'off' (default) | character vector with values 'off', 'all', or 'GRPIndex'

Stack arrows if the cash flows are in the same direction on the same day, specified as the comma-separated pair consisting of 'Stacked' and the following values:

• 'off' — For all groups, all arrows originate from the horizontal line.

• 'all' — For all groups, arrows are stacked if the cash flows are in the same direction on the same day.

• 'GRPIndex' — For specified groups, arrows are stacked if the cash flows are in the same direction on the same day.

Data Types: char

ShowAmnt — Show amount on arrows

'off' (default) | character vector with values 'off' or 'individual' | cell array of character vectors

Show amount on the arrows, specified as the comma-separated pair consisting of 'ShowAmnt' and the following values:

• 'off' — Hide cash flow amounts on arrows.

• 'all' — Show cash flow amounts on arrows.

• [INSTIndex or GRPIndex] — Show cash flow amounts for the specified vector of instruments (when 'Groups' is 'off') or groups.

Data Types: char | cell

DateSpacing — Control for date axis tick spacing

'off' (default) | character vector with values 'off' or TickDateSpace | numeric value for TickDateSpace

Control for data spacing, specified as the comma-separated pair consisting of 'DateSpacing' and the following values:

• 'off' — The date axis ticks are spaced regularly.

• TickDateSpace — The date axis ticks are placed on actual cash flow dates. The ticks skip some cash flows if they are less than TickDateSpace apart.

Data Types: char | double

DateFormat — Date format

'off' display in datetime format (default) | character vector with values 'off' or DateFormNum | numeric value for DateFormNum

Date format, specified as the comma-separated pair consisting of 'DateFormat' and the following values:

• 'off' — The date axis tick labels (Xlabel) are in datetime format.

• DateFormNum — The date format number (2 = 'mm/dd/yy', 6 = 'mm/dd', and 10 = 'yyyy'). Additional values for DateFormNum are as follows:

  DateFormNum	Example
  2	03/01/00
  3	Mar
  5	03
  6	03/01
  7	01
  8	Wed
  9	W
  10	2000
  11	00
  12	Mar00
  17	Q1–00
  18	Q1
  19	01/03
  20	01/03/00
  27	Q1–2000
  28	Mar2000
  29	2000–03–01

Data Types: char | double

Output Arguments

h — Handles to line objects

vector

Handles to line objects, returned as a NINST-by-3 matrix of handles to line objects, containing [hLines, hUArrowHead, hDArrowHead] where:

• hLines — Horizontal and vertical lines used in the cash flow diagram

• hUArrowHead — "Up" arrowheads

• hDArrowHead — "Down" arrowheads

axes_handle — Handles to axes for plot or subplots

vector

Handles to axes for the plot or subplots, returned as a (Number of axes)-by-1 vector of handles to axes.

Version History

Introduced in R2013a

R2025a: Default Display Change for DateFormat

The default display for the DateFormat name-value argument changes from datenum to datetime.