fanplot

Plot combined historical and forecast data to visualize possible outcomes

Syntax

fanplot(historical,forecast)

fanplot(___,Name,Value)

fanplot(ax,historical,forecast)

fanplot(___,Name,Value)

h = fanplot(ax,historical,forecast)

[h,ax] = fanplot(___,Name,Value)

Description

fanplot(historical,forecast) generates a fan chart. In time series analysis, a fan chart is a chart that joins a simple line chart for observed past data with ranges for possible values of future data. The historical data and possible future data are joined with a line showing a central estimate or most likely value for the future outcomes.

fanplot supports three plotting scenarios:

• Matching — This scenario occurs when the time period perfectly matches for historical and forecast data.

• Backtest — This scenario occurs when there are overlaps between historical and forecast data.

• Gap — This scenario occurs when there are NaN values in the historical or forecast data.

fanplot(___,Name,Value) generates a fan chart using optional name-value pair arguments.

fanplot(ax,historical,forecast) generates a fan chart using an optional ax argument.

fanplot(___,Name,Value) generates a fan chart using optional name-value pair arguments.

h = fanplot(ax,historical,forecast) generates a fan chart and returns the figure handle h. In time series analysis, a fan chart is a chart that joins a simple line chart for observed past data with ranges for possible values of future data. The historical data and possible future data are joined with a line showing a central estimate or most likely value for the future outcomes.

fanplot supports three plotting scenarios:

• Matching — This scenario occurs when the time period perfectly matches for historical and forecast data.

• Backtest — This scenario occurs when there are overlaps between historical and forecast data.

• Gap — This scenario occurs when there are NaN values in the historical or forecast data.

[h,ax] = fanplot(___,Name,Value) generates a fan chart and returns the figure handle h and axis (ax) using optional name-value pair arguments.

Examples

Create a Fan Plot Using Cell Array Data

Define the data inputs for historical as a 5-by-2 cell array and forecast as a 5-by-21 cell array with 20 observations.

historical =  {2006    -0.0110
               2007     0.0120
               2008     0.0090
               2009     0.0120
               2010     0.0150};

forecast =    {2011  0.0203      -0.0155     0.0311     -0.0026      0.0035    0.0049      0.0026    0.0298    -0.0212      0.0128    ...
                     0.0533       0.0139     0.0037     -0.0727     -0.0291   -0.0058      0.0183    0.0490     0.0072     -0.0604;
               2012  0.0430      -0.0094     0.0587      0.0095      0.0185    0.0205      0.0172    0.0569    -0.0177      0.0320    ...
                     0.0141       0.0337     0.0187      0.0132     -0.0292    0.0048      0.0400    0.0126     0.0239      0.0124;
               2013  0.0518      -0.0116     0.0708      0.0112      0.0221    0.0246      0.0205    0.0686    -0.0217      0.0385    ...
                     0.0168       0.0405     0.0224      0.0157     -0.0356    0.0056      0.0482    0.0150     0.0286      0.0148;
               2014  0.0546      -0.0171     0.0762      0.0088      0.0210    0.0239      0.0193    0.0737    -0.0285      0.0396    ...
                     0.0151       0.0419     0.0214      0.0139     -0.0442    0.0024      0.0506    0.0130     0.0284      0.0128;
               2015  0.0565      -0.0207     0.0797      0.0072      0.0203    0.0234      0.0185    0.0770    -0.0329      0.0404    ...
                     0.0139       0.0428     0.0207      0.0126     -0.0499    0.0026      0.0522    0.0117     0.0283      0.0115};

Generate the fan plot.

fanplot (historical, forecast);

The dotted points are the historical lines and the filled lines indicate the mean for the forecasts. This fanplot represents a matching scenario where the time period perfectly matches for the historical and forecast data.

Create a Fan Plot Using Matrix Data

Define the data inputs for historical as a 5-by-2 matrix and forecast as a 5-by-21 matrix with 20 observations.

historical =  [ 1.0000    2.8046 ; 
                2.0000    4.1040 ; 
                3.0000    6.7292 ; 
                4.0000    8.6486 ; 
                5.0000   10.4747 ];



forecast  =   [ 3.0000   28.9874   18.3958   19.6376   29.5627    8.3462    7.1502   25.3845    2.2963    8.0517   13.1328   19.5155   14.7369 , ...                                           
                         20.8557   27.0691   23.0803   20.7885   18.0205   17.2294   10.0197   29.4254 ;

                4.0000    4.8933   27.2659    7.2206   24.4703   10.5895   15.0212   29.1137    6.3784   10.2638   11.0671   12.6656    4.3285 , ...
                          8.0007   18.7114   19.1691   24.5963    4.2835    4.0676    3.2612   29.5784 ;
                                
                5.0000   20.9732   19.7069   11.6862   25.7018   31.8940    7.2664   19.2113   10.0001   31.5482   25.7193   13.8881   30.1476 , ... 
                         31.7996    3.6419    3.2695   27.1422   10.5487   32.6529   18.8370    6.6373 ;

                6.0000   11.0069   29.1965    4.5551   20.2627   10.9209   15.2675   28.5359   11.4010   14.4001   14.7923    6.0546   12.4509 , ...
                         23.9532   18.4804   25.5484    4.8747    8.0036   11.5329   11.6807   21.7583 ;

                7.0000    5.9699   11.1486   26.0449   13.4619   21.1196   28.8068   26.2525   10.1085   13.9197    8.7470   31.0149   23.4163 , ...
                         21.2390   29.2396   18.4828   28.3945   21.9342   14.4642   17.2613   15.7896 ];

Generate the fan plot and return the figure handle (h) and axis object (ax).

[h,ax] = fanplot(historical, forecast)

h = 
  Figure (1) with properties:

      Number: 1
        Name: ''
       Color: [1 1 1]
    Position: [167 243 560 337.1852]
       Units: 'pixels'

  Show all properties

ax = 
  Axes (Financial Forecast Chart) with properties:

             XLim: [1 7]
             YLim: [0 35]
           XScale: 'linear'
           YScale: 'linear'
    GridLineStyle: '-'
         Position: [0.1300 0.1100 0.7750 0.8150]
            Units: 'normalized'

  Show all properties

The dotted points are the historical lines and the filled lines indicate the mean for the forecasts. This fanplot represents a backtest scenario where there is an overlap between the historical and forecast data.

Create Fan Plot Using Cell Array Data and Customize the Plot With Name-Value Pair Arguments

Define the data inputs for historical as a 5-by-2 cell array and forecast as a 5-by-21 cell array with 20 observations.

historical =  {2006    -0.0110
               2007     0.0120
               2008     0.0090
               2009     0.0120
               2010     0.0150};

forecast =    {2011  0.0203      -0.0155     0.0311     -0.0026      0.0035    0.0049      0.0026    0.0298    -0.0212      0.0128    ...
                     0.0533       0.0139     0.0037     -0.0727     -0.0291   -0.0058      0.0183    0.0490     0.0072     -0.0604;
               2012  0.0430      -0.0094     0.0587      0.0095      0.0185    0.0205      0.0172    0.0569    -0.0177      0.0320    ...
                     0.0141       0.0337     0.0187      0.0132     -0.0292    0.0048      0.0400    0.0126     0.0239      0.0124;
               2013  0.0518      -0.0116     0.0708      0.0112      0.0221    0.0246      0.0205    0.0686    -0.0217      0.0385    ...
                     0.0168       0.0405     0.0224      0.0157     -0.0356    0.0056      0.0482    0.0150     0.0286      0.0148;
               2014  0.0546      -0.0171     0.0762      0.0088      0.0210    0.0239      0.0193    0.0737    -0.0285      0.0396    ...
                     0.0151       0.0419     0.0214      0.0139     -0.0442    0.0024      0.0506    0.0130     0.0284      0.0128;
               2015  0.0565      -0.0207     0.0797      0.0072      0.0203    0.0234      0.0185    0.0770    -0.0329      0.0404    ...
                     0.0139       0.0428     0.0207      0.0126     -0.0499    0.0026      0.0522    0.0117     0.0283      0.0115};

Generate the fan plot using name-value pair arguments to customize the presentation.

fanplot(historical,forecast,'FanFaceColor',[1 1 1;1 0 0],'FanLineStyle','--','ForecastMarker','p','ForecastMarkerSize',10)

Create a Fan Plot Using Table Data

Create table of historical dates and data.

historicalDates = datetime(2006:2010,1,1)';
historicalData = [-0.0110;0.0120;0.0090;0.0120;0.0150];
historical = table(historicalDates,historicalData,'VariableNames',{'Dates','Data'});

Create table of forecast dates and data.

forecastDates = datetime(2011:2015,1,1)';
forecastData =      [0.0203      -0.0155    0.0311    -0.0026      0.0035    0.0049      0.0026    0.0298    -0.0212       0.0128    ...
                     0.0533       0.0139    0.0037    -0.0727     -0.0291   -0.0058      0.0183    0.0490     0.0072      -0.0604;
                     0.0430      -0.0094    0.0587     0.0095      0.0185    0.0205      0.0172    0.0569    -0.0177       0.0320    ...
                     0.0141       0.0337    0.0187     0.0132     -0.0292    0.0048      0.0400    0.0126     0.0239       0.0124;
                     0.0518      -0.0116    0.0708     0.0112      0.0221    0.0246      0.0205    0.0686    -0.0217       0.0385    ...
                     0.0168       0.0405    0.0224     0.0157     -0.0356    0.0056      0.0482    0.0150     0.0286       0.0148;
                     0.0546      -0.0171    0.0762     0.0088      0.0210    0.0239      0.0193    0.0737    -0.0285       0.0396    ...
                     0.0151       0.0419    0.0214     0.0139     -0.0442    0.0024      0.0506    0.0130     0.0284       0.0128;
                     0.0565      -0.0207    0.0797     0.0072      0.0203    0.0234      0.0185    0.0770    -0.0329       0.0404    ...
                     0.0139      0.0428     0.0207     0.0126     -0.0499    0.0026      0.0522    0.0117     0.0283       0.0115];
forecast = [table(forecastDates,'VariableName',{'Dates'}),array2table(forecastData)];

Plot the data using fanplot and use the Quantiles name-value argument to find the 90th percentile.

fanplot(historical,forecast,Quantiles=0.9);

Input Arguments

historical — Historical dates and data

matrix | cell array | table | timetable

Historical dates and data, specified as an N-by-2 matrix, cell array, table, or timetable where the first column is the date, and the second column is the data associated for that date. N indicates the number of dates. By using the cell array format for the input, you can make the first column datetime and produce the same plot as would serial date numbers or date character vectors. For example:

historical(:,1) = num2cell(datetime(2006:2010,1,1));
forecast(:,1) = num2cell(datetime(2011:2015,1,1));
fanplot (historical, forecast);

Data Types: cell | double | table | timetable

forecast — Forecast dates and data

matrix | cell array of character vectors | table | timetable

Forecast dates and data, specified as an N-by-M matrix, cell array, table, or timetable where the first column is the date, and the second to the last columns are the data observations. N indicates the number of the dates and (M – 1) is the number for data observations. By using the cell array format for the input, you can make the first column datetime and produce the same plot as would serial date numbers or date character vectors. For example:

historical(:,1) = num2cell(datetime(2006:2010,1,1));
forecast(:,1) = num2cell(datetime(2011:2015,1,1));
fanplot (historical, forecast);

Data Types: cell | double | table | timetable

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: fanplot(historical,forecast,'NumQuantiles',14,'FanLineColor','blue','HistoricalLineWidth', 1.8,'ForecastLineColor','red')

NumQuantiles — Number of quantiles to display

20 (default) | positive integer

Number of quantiles to display in fan chart, specified as a positive integer.

Note

NumQuantiles is ignored if Quantiles is specified.

Data Types: double

Quantiles — Quantiles to display

Use values from NumQuantiles (default) | nonnegative decimal

Since R2025a

Quantiles to display in fan chart, specified as a nonnegative decimal value between 0 and 1.

Note

If Quantiles is specified, then NumQuantiles is ignored.

Data Types: double

FanLineStyle — Style of the lines separating fans

'none' (default) | character vector

Style of the lines separating fans, specified as a character vector. For more information on supported character vectors for line styles, see Line Properties.

Data Types: char

FanLineColor — Color of lines separating fans

axes dependent (default) | character vector for color or RGB triplet

Color of lines separating fans, specified as a character vector for color or an RGB triplet. For more information on supported color character vectors, see Line Properties.

Data Types: double | char

FanFaceColor — Color of each fan

[1 1 0;1 0 0] (yellow to red) (default) | matrix

Color of each fan, specified as an N-by-3 matrix controlling the color of each fan, where each row is an RGB triplet. There are three possible values of N:

• When N = NumQuantiles, the color of each fan is specified by the corresponding row in the matrix.

• When N = ceil(NumQuantiles/2), the specified colors represent the bottom half of the fans. The colors of the top half are determined by reversing the order of these colors. For more information, see ceil.

• When N = 2, the colors in the bottom half of the fan are a linear interpolation between the two specified colors. The pattern is reversed for the top half.

Data Types: double

HistoricalMarker — Marker symbol of historical line

'o' (default) | character vector

Marker symbol of historical line, specified as a character vector. For more information on supported character vectors for markers, see Line Properties.

Data Types: char

HistoricalMarkerSize — Marker size of historical line

5 (default) | positive value in point units

Marker size of historical line, specified as a positive value in point units.

Data Types: double | char

HistoricalMarkerFaceColor — Marker fill color of historical line

axes dependent (default) | character vector with a value of 'none', 'auto', color identifier, or RGB triplet

Marker fill color of historical line, specified as a character vector with a value of 'none', 'auto', a character vector for color, or an RGB triplet. For more information on supported character vectors for color, see Line Properties.

Data Types: double | char

HistoricalMarkerEdgeColor — Marker outline color of historical line

axes dependent (default) | character vector with a value of 'none', 'auto', color identifier, or RGB triplet

Marker outline color of historical line, specified as a character vector with a value of 'none', 'auto', a character vector for color, or an RGB triplet. For more information on supported character vectors for color, see Line Properties.

Data Types: double | char

HistoricalLineColor — Color of historical line

axes dependent (default) | character vector with a value of 'none', color identifier, or RGB triplet

Color of historical line, specified as a character vector with a value of 'none', a character vector for color, or an RGB triplet. For more information on supported character vectors for color, see Line Properties.

Data Types: double | char

HistoricalLineStyle — Style of historical line

'--' (default) | character vector

Style of historical line, specified as a character vector. For more information on supported character vectors for line styles, see Line Properties.

Data Types: char

HistoricalLineWidth — Width of historical line

1 (default) | positive value in point units

Width of historical line, specified as a positive value in point units.

Data Types: double

ForcecastMarker — Marker symbol of forecast line

'none' (default) | character vector

Marker symbol of forecast line, specified as a character vector. For more information on supported character vectors for marker symbols, see Line Properties.

Data Types: char

ForecastMarkerSize — Marker size of forecast line

5 (default) | positive value in point units

Marker size of forecast line, specified as a positive value in point units.

Data Types: double

ForecastMarkerFaceColor — Marker fill color of forecast line

'none' (default) | character vector with a value of 'none', 'auto', color identifier, or RGB triplet

Marker fill color of forecast line, specified as a character vector with a value of 'none', 'auto', a character vector for color, or an RGB triplet. For more information on supported character vectors for color, see Line Properties.

Data Types: double | char

ForecastMarkerEdgeColor — Marker outline color of forecast line

'auto' (default) | character vector with a value of 'none', 'auto', color identifier, or RGB triplet

Marker outline color of forecast line, specified as a character vector with a value of 'none', 'auto', character vector for color, or an RGB triplet. For more information on supported character vectors for color, see Line Properties.

Data Types: double | char

ForecastLineColor — Color of forecast line

axes dependent (default) | character vector with a value of 'none', color identifier, or RGB triplet

Color of forecast line, specified as a character vector with a value of 'none', a character vector for color, or an RGB triplet. For more information on supported character vectors for color, see Line Properties.

Data Types: double | char

ForecastLineStyle — Style of forecast line

'-' (default) | character vector

Style of forecast line, specified as a character vector. For more information on supported character vectors for line styles, see Line Properties.

Data Types: char

ForecastLineWidth — Width of forecast line

1 (default) | positive value in point units

Width of forecast line, specified as a positive value in point units.

Data Types: double

Output Arguments

h — Figure handle for fanplot

handle object

Figure handle for the fanplot, returned as handle object.

ax — Axis object

axis object

Since R2025a

Axis object, returned as an ax object.

Version History

Introduced in R2014b

R2025a: Added Name-Value Argument for Quantiles

Use the name-value argument for Quantiles to specify quantiles displayed in the fan chart.

R2025a: Additional output argument for ax

You can specify an additional output argument for ax that retunes an axis object.