Main Content


Add business calendar awareness to timetables



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) specifies options using one or more optional name-value pair arguments in addition to the input arguments in the previous syntax. For example, TT = addBusinessCalendar(TT,'Holidays',H) specifies a list of holidays specified as a datetime vector that replaces the default holidays found in holidays.m. You can specify more than one name-value pair argument.


collapse all

This example shows how to add a business calendar when you calculate period-over-period (PoP) rolling differences for 5 years of simulated daily prices. For each date in timetable TT, the difference represents the PoP difference of the corresponding price compared to the price one period earlier.

Use holidays to indicate the holidays in holidays.m for the simulation period.

H = holidays(datetime(2014,1,1),datetime(2018,12,31));

Simulate daily prices for three assets.

t = (datetime(2014,1,1):caldays:datetime(2018,12,31))';
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);
ans=15×3 timetable
       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 

Use addBusinessCalendar to indicate the holidays for the simulation period in the timetable TT.

TT = addBusinessCalendar(TT,'Holidays',H);

Use rollingreturns with the 'Method' name-value pair argument set to 'difference' to compute the differences, that is, the period-over-period changes.

deltas = rollingreturns(TT,'Period',calweeks(1),'Method','difference');
ans=15×3 timetable
       Time        Price_Difference_1w    Price2_Difference_1w    Price3_Difference_1w
    ___________    ___________________    ____________________    ____________________

    01-Jan-2014            NaN                     NaN                     NaN        
    02-Jan-2014            NaN                     NaN                     NaN        
    03-Jan-2014            NaN                     NaN                     NaN        
    04-Jan-2014            NaN                     NaN                     NaN        
    05-Jan-2014            NaN                     NaN                     NaN        
    06-Jan-2014            NaN                     NaN                     NaN        
    07-Jan-2014            NaN                     NaN                     NaN        
    08-Jan-2014            NaN                     NaN                     NaN        
    09-Jan-2014           0.04                    0.04                    0.04        
    10-Jan-2014           0.06                    0.06                    0.05        
    11-Jan-2014           0.08                    0.08                    0.07        
    12-Jan-2014           0.11                     0.1                     0.1        
    13-Jan-2014            0.1                    0.09                    0.09        
    14-Jan-2014            0.1                    0.09                    0.09        
    15-Jan-2014            0.1                    0.09                    0.09        

Input Arguments

collapse all

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

Data Types: timetable

Name-Value Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: TT = addBusinessCalendar(TT,'Holidays',H)

Alternate holidays and market closure dates, specified as the comma-separated pair consisting of 'Holidays' and a vector of datetimes. The dates in Holidays must be whole dates, without any HH:MM:SS components. No business is conducted on the dates in Holidays. For more information, see holidays and isbusday.

You can generate alternate holiday schedules by using the createholidays function. To do so, perform the following steps:

  1. Generate a new holidays function using createholidays.

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

  3. Pass the alternate holidays to addBusinessCalendar using the 'Holidays' name-value pair argument.

Data Types: char | double

Alternate weekend days on which no business is conducted, specified as the comma-separated pair consisting of 'Weekends' and a logical vector with seven elements in which true (1) indicates a weekend day and false (0) indicates a weekday. The elements of 'Weekends' are encoded as Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday. You can also specify 'Weekends' as a string vector whose elements explicitly list the weekend days. If business is conducted seven days per week, then specify 'Weekends' as [0 0 0 0 0 0 0].

Data Types: logical

Output Arguments

collapse all

Updated timetable TT with added business calendar awareness by a 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.

Introduced in R2020b