cfplot

R2026b

Visualize cash flows of financial instruments

collapse all in page

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.

example

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

example

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

example

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

example

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

example

Examples

collapse all

Open Live Script

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])

Figure contains an axes object. The axes object contains 17 objects of type line, text. One or more of the lines displays its values using only markers

Group the second and third cash flows. 

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

Figure contains an axes object. The axes object contains 11 objects of type line, text. One or more of the lines displays its values using only markers

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);

Figure contains an axes object. The axes object contains 11 objects of type line, text. One or more of the lines displays its values using only markers

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);

Figure contains an axes object. The axes object contains 11 objects of type line, text. One or more of the lines displays its values using only markers

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');

Figure contains 2 axes objects. Axes object 1 with title Group 1 contains 6 objects of type line, text. One or more of the lines displays its values using only markers Axes object 2 with title Group 2 contains 6 objects of type line. One or more of the lines displays its values using only markers

Open Live Script

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])

Figure contains an axes object. The axes object contains 17 objects of type line, text. One or more of the lines displays its values using only markers

Input Arguments

collapse all

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

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

(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

collapse all

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)

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

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

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

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

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:

    DateFormNumExample
    2 03/01/00
    3Mar
    503
    603/01
    701
    8Wed
    9W
    102000
    1100
    12Mar00
    17Q1–00
    18Q1
    1901/03
    2001/03/00
    27Q1–2000
    28Mar2000
    292000–03–01

Data Types: char | double

Output Arguments

collapse all

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

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

expand all

See Also

| | (Financial Instruments Toolbox) |

Topics