convert2semiannual

Aggregate timetable data to semiannual periodicity

Since R2021a

Syntax

TT2 = convert2semiannual(TT1)

TT2 = convert2semiannual(TT1,Name,Value)

Description

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

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

Examples

Aggregate Timetable Data to Semiannual Periodicity

Load the simulated stock price data and corresponding logarithmic returns in SimulatedStockSeries.mat.

load SimulatedStockSeries

The timetable DataTimeTable contains measurements recorded at various, irregular times during trading hours (09:30 to 16:00) of the New York Stock Exchange (NYSE) from January 1, 2018, through December 31, 2020.

For example, display the first few observations.

head(DataTimeTable)

            Time            Price     Log_Return
    ____________________    ______    __________

    01-Jan-2018 11:52:48       100     -0.025375
    01-Jan-2018 13:23:13    101.14      0.011336
    01-Jan-2018 14:45:09     101.5     0.0035531
    01-Jan-2018 15:30:30    100.15      -0.01339
    02-Jan-2018 10:43:37     99.72    -0.0043028
    03-Jan-2018 10:02:21    100.11     0.0039033
    03-Jan-2018 11:22:37    103.96      0.037737
    03-Jan-2018 13:42:27    107.05       0.02929

DataTimeTable does not include business calendar awareness. If you want to account for nonbusiness days (weekends, holidays, and market closures) and you have a Financial Toolbox™ license, add business calendar awareness by using the addBusinessCalendar function.

Aggregate the price series to a semiannual series by reporting the final price of each January-to-June period and July-to-December period.

SemiannualPrice = convert2semiannual(DataTimeTable(:,"Price"));
tail(SemiannualPrice)

       Time        Price 
    ___________    ______

    30-Jun-2018     99.29
    31-Dec-2018     84.26
    30-Jun-2019    169.77
    31-Dec-2019    153.22
    30-Jun-2020    224.29
    31-Dec-2020    301.04

SemiannualPrice is a timetable containing the final prices for each reported semiannual period in DataTimeTable.

Specify Aggregation Method for Each Variable

This example shows how to specify the appropriate aggregation method for the units of a variable. It also shows how to use convert2semiannual to aggregate both intra-day data and aggregated quarterly data, which result in equivalent semiannual aggregates.

Load the simulated stock price data and corresponding logarithmic returns in SimulatedStockSeries.mat.

load SimulatedStockSeries

The price series Price contains absolute measurements, whereas the log returns series Log_Return is the rate of change of the price series among successive observations. Because the series have different units, you must specify the appropriate method when you aggregate the series. Specifically, if you report the final price for a given periodicity, you must report the sum of the log returns within each period.

To understand how to maintain consistency among aggregation methods, use two approaches to aggregate DataTimeTable so that the result has a semiannual periodicity.

1. Pass DataTimeTable directly to convert2semiannual.

2. Aggregate DataTimeTable so that the result has a quarterly periodicity by using convert2quarterly, and then pass the result to convert2semiannual.

In both cases, specify reporting the last price and the sum of the log returns for each period.

Directly aggregate the data so that the result has a semiannual periodicity. For each series, specify the aggregation method that is appropriate for the unit.

aggmethods = ["lastvalue" "sum"];
SemiannualTT1 = convert2semiannual(DataTimeTable,Aggregation=aggmethods);
tail(SemiannualTT1)

       Time        Price     Log_Return
    ___________    ______    __________

    30-Jun-2018     99.29    -0.032501 
    31-Dec-2018     84.26     -0.16414 
    30-Jun-2019    169.77      0.70054 
    31-Dec-2019    153.22     -0.10257 
    30-Jun-2020    224.29      0.38107 
    31-Dec-2020    301.04       0.2943 

SemiannualTT1 is a timetable containing the semiannual data. Price is a series of the final stock prices for each January-to-June period and July-to-December period, and Log_Return is the sum of the log returns for each semiannual period.

Aggregate the data in two steps: aggregate the data so that the result has a quarterly periodicity, then aggregate the quarterly data to semiannual data. For each series, specify the aggregation method that is appropriate for the unit.

QuarterlyTT = convert2quarterly(DataTimeTable,Aggregation=aggmethods);
tail(QuarterlyTT)

       Time        Price     Log_Return
    ___________    ______    __________

    31-Mar-2019    112.93      0.29286 
    30-Jun-2019    169.77      0.40768 
    30-Sep-2019    148.97      -0.1307 
    31-Dec-2019    153.22      0.02813 
    31-Mar-2020    229.88      0.40568 
    30-Jun-2020    224.29    -0.024618 
    30-Sep-2020    246.77     0.095517 
    31-Dec-2020    301.04      0.19879 

SemiannualTT2 = convert2semiannual(QuarterlyTT,Aggregation=aggmethods)

SemiannualTT2=6×2 timetable
       Time        Price     Log_Return
    ___________    ______    __________

    30-Jun-2018     99.29    -0.032501 
    31-Dec-2018     84.26     -0.16414 
    30-Jun-2019    169.77      0.70054 
    31-Dec-2019    153.22     -0.10257 
    30-Jun-2020    224.29      0.38107 
    31-Dec-2020    301.04       0.2943 

QuarterlyTT is a timetable with quarterly periodicity. Price is a series of the final stock prices for each quarter, and Log_Return is the sum of the log returns for each quarter.

SemiannualTT1 and SemiannualTT2 are equal.

Input Arguments

TT1 — Data to aggregate to semiannual periodicity

timetable

Data to aggregate to a semiannual 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 = convert2semiannual(TT1,'Aggregation',["lastvalue" "sum"])

Aggregation — Aggregation method for semiannual period to semiannual periodicity (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 a semiannual period to semiannual periodicity (inter-day aggregation), 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, convert2semiannual applies the specified method to all time series in TT1. If you specify a string vector or cell vector aggregation, convert2semiannual applies aggregation(j) to TT1(:,j); convert2semiannual 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.02    200.04    300.06     400.08
      03-Jan-2018     99.96    199.92    299.88     399.84
          .             .         .         .          .
          .             .         .         .          .
          .             .         .         .          .
      28-Jun-2018     69.63    139.26    208.89     278.52
      29-Jun-2018     70.15     140.3    210.45     280.60
      30-Jun-2018     75.77    151.54    227.31     303.08
      01-Jul-2018     75.68    151.36    227.04     302.72
      02-Jul-2018     71.34    142.68    214.02     285.36
      03-Jul-2018     69.25    138.50    207.75     277.00
          .             .         .         .          .
          .             .         .         .          .
          .             .         .         .          .
      29-Dec-2018    249.16    498.32    747.48     996.64
      30-Dec-2018    250.21    500.42    750.63    1000.84
      31-Dec-2018    256.75    513.50    770.25    1027.00

The corresponding default semiannual results representing TT2 (in which all days are business days and the 'lastvalue' is reported on the last business day of each semiannual period) are as follows.

           Time         AAA       BBB            CCC       
      ___________    ______    ______    ________________
      30-Jun-2018     75.77    151.54    227.31    303.08
      31-Dec-2018    256.75    513.50    770.25   1027.00

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

Output Arguments

TT2 — Semiannual data

timetable

Semiannual data, returned as a timetable. convert2semiannual reports semiannual aggregation results on the last business day of June and December. 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, convert2semiannual returns a NaN for that variable and annual period in TT2.

The first date in TT2 is the last business date of the semiannual period in which the first date in TT1 occurs, provided TT1 has business dates in that semiannual period. Otherwise the first date in TT2 is the next end-of-semiannual-period business date.

The last date in TT2 is the last business date of the semiannual period in which the last date in TT1 occurs, provided TT1 has business dates in that semiannual period. Otherwise the last date in TT2 is the previous end-of-semiannual-period business date.

Version History

Introduced in R2021a