addBusinessCalendar

Add business calendar awareness to timetables

Since R2020b

Syntax

TT = addBusinessCalendar(TT)

TT = addBusinessCalendar(___,Name=Value)

Description

TT = addBusinessCalendar(TT) adds business calendar awareness to an input timetable TT by setting a custom property for the output timetable TT.

TT = addBusinessCalendar(___,Name=Value) sets additional options specified by one or more name-value arguments, using any of the input arguments in the previous syntax. For example, TT = addBusinessCalendar(TT,Holidays=H) replaces the default holidays stored in Data_NYSE_Closures.mat with the list of holidays H.

Examples

Add Business Calendar Awareness to Timetable

This example shows how to add a business calendar when you aggregate daily prices to weekly simulated prices.

Simulate daily prices for three assets from January 1, 2014, through December 31, 2018.

t = (datetime(2014,1,1):caldays:datetime(2018,12,31))';
rng(200,"twister")
Price = 100 + 0.1*(0:numel(t) - 1)'.*cumsum(randn(numel(t),1)/100); 
Price = round(Price*100)/100;       
Price2 = round(Price*94)/100; 
Price3 = round(Price*88)/100;

TT = timetable(Price,Price2,Price3,RowTimes=t);
head(TT,15)

       Time        Price     Price2    Price3
    ___________    ______    ______    ______

    01-Jan-2014       100       94        88 
    02-Jan-2014       100       94        88 
    03-Jan-2014       100       94        88 
    04-Jan-2014       100       94        88 
    05-Jan-2014    100.01    94.01     88.01 
    06-Jan-2014    100.01    94.01     88.01 
    07-Jan-2014    100.02    94.02     88.02 
    08-Jan-2014    100.02    94.02     88.02 
    09-Jan-2014    100.04    94.04     88.04 
    10-Jan-2014    100.06    94.06     88.05 
    11-Jan-2014    100.08    94.08     88.07 
    12-Jan-2014    100.11     94.1      88.1 
    13-Jan-2014    100.11     94.1      88.1 
    14-Jan-2014    100.12    94.11     88.11 
    15-Jan-2014    100.12    94.11     88.11 

TT.Properties

ans = 
  TimetableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Time'  'Variables'}
           VariableNames: {'Price'  'Price2'  'Price3'}
           VariableTypes: ["double"    "double"    "double"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [1826x1 datetime]
               StartTime: 01-Jan-2014
              SampleRate: NaN
                TimeStep: 1d
                  Events: []
        CustomProperties: No custom properties are set.
      Use addprop and rmprop to modify CustomProperties.

Add business calendar awareness to the timetable.

TTBCA = addBusinessCalendar(TT);
TTBCA.Properties

ans = 
  TimetableProperties with properties:

             Description: ''
                UserData: []
          DimensionNames: {'Time'  'Variables'}
           VariableNames: {'Price'  'Price2'  'Price3'}
           VariableTypes: ["double"    "double"    "double"]
    VariableDescriptions: {}
           VariableUnits: {}
      VariableContinuity: []
                RowTimes: [1826x1 datetime]
               StartTime: 01-Jan-2014
              SampleRate: NaN
                TimeStep: 1d
                  Events: []

   Custom Properties (access using t.Properties.CustomProperties.<name>):
        BusinessCalendar: [1x1 struct]

TTBCA is a timetable containing the same data as TT, but the Time variable respects business days only when you operate on the timetable with business calendar aware functions.

Aggregate the variables in each timetable to weekly mean series.

TTW = convert2weekly(TT,Aggregation="mean");
TTBCAW = convert2weekly(TTBCA,Aggregation="mean");
head(TTW)

       Time        Price     Price2    Price3
    ___________    ______    ______    ______

    03-Jan-2014       100        94        88
    10-Jan-2014    100.02    94.023    88.021
    17-Jan-2014    100.12    94.109    88.104
    24-Jan-2014    100.22    94.203    88.191
    31-Jan-2014    100.37    94.343    88.321
    07-Feb-2014    100.54     94.51    88.479
    14-Feb-2014    100.64    94.599    88.561
    21-Feb-2014    100.83    94.784    88.734

head(TTBCAW)

       Time        Price     Price2    Price3
    ___________    ______    ______    ______

    03-Jan-2014       100        94        88
    10-Jan-2014    100.03     94.03    88.028
    17-Jan-2014    100.13    94.116    88.112
    24-Jan-2014    100.26     94.24    88.228
    31-Jan-2014    100.39    94.364    88.342
    07-Feb-2014    100.56    94.522     88.49
    14-Feb-2014    100.66    94.616    88.576
    21-Feb-2014    100.88    94.833    88.778

TTW contains the weekly means for all days in the data, but TTBCAW contains weekly means for only business days during each week.

Specify Custom Holidays

Simulate daily prices for three assets from January 1, 2014, through December 31, 2018.

t = (datetime(2014,1,1):caldays:datetime(2018,12,31))';
rng(200,"twister")
Price = 100 + 0.1*(0:numel(t) - 1)'.*cumsum(randn(numel(t),1)/100); 
Price = round(Price*100)/100;       
Price2 = round(Price*94)/100; 
Price3 = round(Price*88)/100;

TT = timetable(Price,Price2,Price3,RowTimes=t);

Suppose that the assets are owned by a company that observes all NYSE holidays and a holiday on August 10.

Create a datetime vector containing the custom holiday list.

load Data_NYSE_Closures % Data containing closures excluding Sundays
NYSE_Holidays = NYSE(day(NYSE.Date,"dayofweek") ~= 7,:); % Exclude Saturdays
aug10 = datetime(2014:2018,08,10)';
holidays = [aug10; NYSE.Date(isbetween(NYSE.Date,t(1),t(end),"closed"))];

Add business calendar awareness to the timetable. Specify the custom holiday list.

TTCH = addBusinessCalendar(TT,Holidays=holidays);

TTCH is a timetable containing the same data as TT, but the Time variable respects the custom business days only when you operate on the timetable with business calendar aware functions.

Create a timetable respecting the default business days.

TTBCA = addBusinessCalendar(TT);

Aggregate the timetables by computing the annual means of the prices.

TTY = convert2annual(TT,Aggregation="mean")

TTY=5×3 timetable
       Time        Price     Price2    Price3
    ___________    ______    ______    ______

    31-Dec-2014    103.38    97.177    90.974
    31-Dec-2015    120.53     113.3    106.07
    31-Dec-2016    135.12    127.01     118.9
    31-Dec-2017     151.4    142.31    133.23
    31-Dec-2018    196.83    185.02    173.21

TTBCAY = convert2annual(TTBCA,Aggregation="mean")

TTBCAY=5×3 timetable
       Time        Price     Price2    Price3
    ___________    ______    ______    ______

    31-Dec-2014    103.38    97.175    90.973
    31-Dec-2015    120.66    113.42    106.18
    30-Dec-2016    135.19    127.08    118.97
    29-Dec-2017    151.41    142.33    133.24
    31-Dec-2018    196.55    184.75    172.96

TTCHY = convert2annual(TTCH,Aggregation="mean")

TTCHY=5×3 timetable
       Time        Price     Price2    Price3
    ___________    ______    ______    ______

    31-Dec-2014    103.38    97.175    90.973
    31-Dec-2015    120.64     113.4    106.16
    30-Dec-2016    135.21    127.09    118.98
    29-Dec-2017    151.33    142.25    133.17
    31-Dec-2018    196.53    184.74    172.94

Input Arguments

TT — Input timetable to update with business calendar awareness

timetable

Input timetable to update with business calendar awareness, specified as a timetable.

Data Types: timetable

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: TT = addBusinessCalendar(TT,Holidays=H) replaces the default holidays stored in Data_NYSE_Closures.mat with the list of holidays H

Holidays — Alternate holidays and market closure dates

datetime vector

Alternate holidays and market closure dates, specified as a datetime vector. The dates in Holidays must be whole dates without HH:MM:SS components. No business is conducted on the dates in Holidays.

By default, Holidays is the New York Stock Exchange (NYSE) holidays and market closure dates. For more details, load the default holidays in Data_NYSE_Closures.mat and inspect the NYSE variable, or, if you have a Financial Toolbox™ license, see holidays and isbusday.

Tip

If you have a Financial Toolbox license, you can generate alternate holiday schedules by using the createholidays function and performing this procedure:

1. Generate a new holidays function using createholidays.

2. Call the new holidays function to get the list of holidays.

3. Specify the alternate holidays to addBusinessCalendar by using the Holidays name-value argument.

Data Types: datetime

Weekends — Alternate weekend days on which no business is conducted

[1 0 0 0 0 0 1] or ["Sunday" "Saturday"] (default) | logical vector | string vector

Alternate weekend days on which no business is conducted, specified as a length 7 logical vector or a string vector.

For a logical vector, true (1) entries indicate a weekend day and false (0) entries indicate a weekday, where entries correspond to Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday.

Example: Weekends=[1 0 0 0 0 1 1] specifies that business is not conducted on Fridays through Sundays.

For a string vector, entries explicitly list the weekend days.

Example: Weekends=["Friday" "Saturday" "Sunday"]

Tip

If business is conducted seven days per week, set Weekends to [0 0 0 0 0 0 0].

Data Types: logical

Output Arguments

TT — Updated timetable TT with added business calendar awareness by a custom property

timetable

Updated timetable TT with added business calendar awareness by the custom property BusinessCalendar, returned as a timetable.

The custom property BusinessCalendar contains a data structure that contains a field IsBusinessDay that stores a callable function (F). The function F accepts a datetime matrix (D) and returns a logical indicator matrix (I) of the same size: I = F(D). true (1) elements of I indicate that the corresponding element of D occurs on a business day; false (0) elements of I indicate otherwise.

Access the callable function F by using F = TT.Properties.CustomProperties.BusinessCalendar.IsBusinessDay.

Version History

Introduced in R2020b