convert2weekly

Aggregate timetable data to weekly periodicity

Since R2021a

Syntax

TT2 = convert2weekly(TT1)

TT2 = convert2weekly(___,Name,Value)

Description

TT2 = convert2weekly(TT1) aggregates data (for example, data recorded daily) to a weekly periodicity.

TT2 = convert2weekly(___,Name,Value) uses additional options specified by one or more name-value arguments.

Examples

Aggregate Timetable Daily Data to Weekly Periodicity

Apply separate aggregation methods to related variables in a timetable while maintaining consistency between aggregated results when converting from a daily to a weekly periodicity. You can use convert2weekly to aggregate both intra-daily data and aggregated daily data. These methods result in equivalent weekly aggregates.

Load a timetable (TT) of simulated stock price data and corresponding logarithmic returns. The data stored in TT is recorded at various times throughout the day on New York Stock Exchange (NYSE) business days from January 1, 2018, to December 31,2020. The timetable TT also includes NYSE business calendar awareness. If your timetable does not account for nonbusiness days (weekends, holidays, and market closures), add business calendar awareness by using addBusinessCalendar first.

load('SimulatedStock.mat','TT');
head(TT)

            Time            Price     Log_Return
    ____________________    ______    __________

    02-Jan-2018 11:52:11    100.71     0.0070749
    02-Jan-2018 13:23:09    103.11      0.023551
    02-Jan-2018 14:45:30    100.24     -0.028229
    02-Jan-2018 15:30:48    101.37       0.01121
    03-Jan-2018 10:02:21    101.81     0.0043311
    03-Jan-2018 11:22:37    100.17      -0.01624
    03-Jan-2018 14:45:20     99.66    -0.0051043
    03-Jan-2018 14:55:39    100.12     0.0046051

Use convert2daily to aggregate intra-daily prices and returns to daily periodicity. To maintain consistency between prices and returns, for any given trading day, aggregate prices by reporting the last recorded price with "lastvalue" and aggregate returns by summing all logarithmic returns with "sum".

TT1 = convert2daily(TT,'Aggregation',["lastvalue" "sum"]);
head(TT1)

       Time        Price     Log_Return
    ___________    ______    __________

    02-Jan-2018    101.37     0.013607 
    03-Jan-2018    100.12    -0.012408 
    04-Jan-2018    106.76     0.064214 
    05-Jan-2018    112.78     0.054856 
    08-Jan-2018    119.07     0.054273 
    09-Jan-2018    119.46      0.00327 
    10-Jan-2018    124.44     0.040842 
    11-Jan-2018    125.63    0.0095174 

Use convert2weekly to aggregate the data to a weekly periodicity and compare the results of two different aggregation approaches. The first approach computes weekly results by aggregating the daily aggregates and the second approach computes weekly results by directly aggregating the original intra-daily data.

tt1 = convert2weekly(TT1,'Aggregation',["lastvalue" "sum"]);   % Daily to weekly
tt2 = convert2weekly(TT ,'Aggregation',["lastvalue" "sum"]);   % Intra-daily to weekly

head(tt1)

       Time        Price     Log_Return
    ___________    ______    __________

    05-Jan-2018    112.78      0.12027 
    12-Jan-2018    125.93      0.11029 
    19-Jan-2018    117.67    -0.067842 
    26-Jan-2018     118.8    0.0095573 
    02-Feb-2018    120.85     0.017109 
    09-Feb-2018    123.68     0.023147 
    16-Feb-2018    124.33    0.0052417 
    23-Feb-2018    127.09     0.021956 

head(tt2)

       Time        Price     Log_Return
    ___________    ______    __________

    05-Jan-2018    112.78      0.12027 
    12-Jan-2018    125.93      0.11029 
    19-Jan-2018    117.67    -0.067842 
    26-Jan-2018     118.8    0.0095573 
    02-Feb-2018    120.85     0.017109 
    09-Feb-2018    123.68     0.023147 
    16-Feb-2018    124.33    0.0052417 
    23-Feb-2018    127.09     0.021956 

Notice that the results of the two approaches are the same and that convert2weekly reports on Fridays by default. For weeks in which Friday is not an NYSE trading day, the function reports results on the previous business day. In addition, you can use the convert2weekly optional name-value pair argument 'EndOfWeekDay' to specify a different day of the week that ends business weeks.

Input Arguments

TT1 — Data to aggregate to weekly periodicity

timetable

Data to aggregate to a weekly periodicity, specified as a timetable.

Each variable can be a numeric vector (univariate series) or numeric matrix (multivariate series).

Note

• NaNs indicate missing values.

• Timestamps must be in ascending or descending order.

By default, all days are business days. If your timetable does not account for nonbusiness days (weekends, holidays, and market closures), add business calendar awareness by using addBusinessCalendar first. For example, the following command adds business calendar logic to include only NYSE business days.

TT = addBusinessCalendar(TT);

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.

Example: TT2 = convert2weekly(TT1,'Aggregation',["lastvalue" "sum"])

Aggregation — Aggregation method for TT1 data for intra-week or inter-day aggregation

"lastvalue" (default) | "sum" | "prod" | "mean" | "min" | "max" | "firstvalue" | character vector | function handle | string vector | cell vector of character vectors or function handles

Aggregation method for TT1 defining how data is aggregated over business days in an intra-week or inter-day periodicity, specified as one of the following methods, a string vector of methods, or a length numVariables cell vector of methods, where numVariables is the number of variables in TT1.

• "sum" — Sum the values in each year or day.

• "mean" — Calculate the mean of the values in each year or day.

• "prod" — Calculate the product of the values in each year or day.

• "min" — Calculate the minimum of the values in each year or day.

• "max" — Calculate the maximum of the values in each year or day.

• "firstvalue" — Use the first value in each year or day.

• "lastvalue" — Use the last value in each year or day.

• @customfcn — A custom aggregation method that accepts a table variable and returns a numeric scalar (for univariate series) or row vector (for multivariate series). The function must accept empty inputs [].

If you specify a single method, convert2weekly applies the specified method to all time series in TT1. If you specify a string vector or cell vector aggregation, convert2weekly applies aggregation(j) to TT1(:,j); convert2weekly applies each aggregation method one at a time (for more details, see retime). For example, consider a daily timetable representing TT1 with three variables.

        Time           AAA       BBB            CCC       
      ___________    ______    ______    ________________
      01-Jan-2018    100.00    200.00    300.00    400.00
      02-Jan-2018    100.03    200.06    300.09    400.12
      03-Jan-2018    100.07    200.14    300.21    400.28
      04-Jan-2018    100.08    200.16    300.24    400.32
      05-Jan-2018    100.25    200.50    300.75    401.00
      06-Jan-2018    100.19    200.38    300.57    400.76
      07-Jan-2018    100.54    201.08    301.62    402.16
      08-Jan-2018    100.59    201.18    301.77    402.36
      09-Jan-2018    101.40    202.80    304.20    405.60
      10-Jan-2018    101.94    203.88    305.82    407.76
      11-Jan-2018    102.53    205.06    307.59    410.12
      12-Jan-2018    103.35    206.70    310.05    413.40
      13-Jan-2018    103.40    206.80    310.20    413.60
      14-Jan-2018    103.91    207.82    311.73    415.64
      15-Jan-2018    103.89    207.78    311.67    415.56
      16-Jan-2018    104.44    208.88    313.32    417.76
      17-Jan-2018    104.44    208.88    313.32    417.76
      18-Jan-2018    104.04    208.08    312.12    416.16
      19-Jan-2018    104.94    209.88    314.82    419.76

The corresponding default weekly results representing TT2 (in which all days are business days and the 'lastvalue' is reported on Fridays) are as follows.

        Time         AAA       BBB            CCC       
      ___________    ______    ______    ________________
      05-Jan-2018    100.25    200.50    300.75    401.00
      12-Jan-2018    103.35    206.70    310.05    413.40
      19-Jan-2018    104.94    209.88    314.82    419.76

The default 'lastvalue' returns the latest observed value in a given week for all variables in TT1.

All methods omit missing data (NaNs) in direct aggregation calculations on each variable. However, for situations in which missing values appear in the first row of TT1, missing values can also appear in the aggregated results TT2. To address missing data, write and specify a custom aggregation method (function handle) that supports missing data.

Data Types: char | string | cell | function_handle

Daily — Intra-day aggregation method for TT1

"lastvalue" (default) | "sum" | "prod" | "mean" | "min" | "max" | "firstvalue" | character vector | function handle | string vector | cell vector of character vectors or function handles

Intra-day aggregation method for TT1, specified as an aggregation method, a string vector of methods, or a length numVariables cell vector of methods. For more details on supported methods and behaviors, see the 'Aggregation' name-value argument.

Data Types: char | string | cell | function_handle

EndOfWeekDay — Day of week that ends business weeks

"Friday" (weeks end on Friday) (default) | scalar integer with value 1 through 7 | "Sunday" | "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | character vector

Day of the week that ends business weeks, specified as a value in the table.

Value	Day Ending Each Week
"Sunday" or 1	Sunday
"Monday" or 2	Monday
"Tuesday" or 3	Tuesday
"Wednesday" or 4	Wednesday
"Thursday" or 5	Thursday
"Friday" or 6	Friday
"Saturday" or 7	Saturday

If the specified end-of-week day in a given week is not a business day, the preceding business day ends that week.

Data Types: double | char | string

Output Arguments

TT2 — Weekly data

timetable

Weekly data, returned as a timetable. The time arrangement of TT1 and TT2 are the same.

If a variable of TT1 has no business-day records during an annual period within the sampling time span, convert2weekly returns a NaN for that variable and annual period in TT2.

If the first week (week1) of TT1 contains at least one business day, the first date in TT2 is the last business date of week1. Otherwise, the first date in TT2 is the next end-of-week business date of TT1.

If the last week (weekT) of TT1 contains at least one business day, the last date in TT2 is the last business date of weekT. Otherwise, the last date in TT2 is the previous end-of-week business date of TT1.

Version History

Introduced in R2021a