isregular

Determine if input times are regular with respect to time or calendar unit

Syntax

tf = isregular(D)

tf = isregular(D,timeUnit)

[tf,dt] = isregular(___)

Description

tf = isregular(D) returns 1 (true) if the input times are regular. Otherwise, it returns 0 (false). The input array D is regular if its times are in a sequence that is strictly monotone (either increasing or decreasing) with a unique time step.

The input argument D can be a:

• datetime vector. (since R2021b)

• duration vector. (since R2021b)

• Timetable. It is regular if its vector of row times is regular.

This syntax is equivalent to isregular(D,'time').

tf = isregular(D,timeUnit) determines if D is regular with respect to the specified time or calendar unit.

For example, D might be regular with respect to months, but irregular with respect to exact elapsed time because different months can have different numbers of days. To determine if D is regular with respect to months, specify timeUnit as 'months'.

[tf,dt] = isregular(___) returns dt, the time step between consecutive times. If D is regular, then dt is either a duration value or a calendarDuration value. If D is not regular, then dt is a NaN value.

Examples

Determine If Vector Is Regular

Create a duration vector by using the seconds function.

D = seconds(1:5)

D = 1x5 duration
   1 sec   2 sec   3 sec   4 sec   5 sec

Test D using the isregular function. D is regular because the time interval between consecutive elements is always the same.

tf = isregular(D)

tf = logical
   1

Change the last element of D.

D(end) = seconds(10)

D = 1x5 duration
    1 sec    2 sec    3 sec    4 sec   10 sec

D is no longer regular.

tf = isregular(D)

tf = logical
   0

Timetable with Monthly Time Step

Create a timetable using a monthly datetime vector. Determine whether it is regular with respect to time, and then with respect to months.

First, create a timetable whose row times are the first five months of the year 2016, stored as datetime values. Add the monthly price of a stock as a timetable variable.

StockPrice = [109.0;107.82;113.17;128.01;116];
M = timetable(datetime(2016,1:5,3)',StockPrice)

M=5×1 timetable
       Time        StockPrice
    ___________    __________

    03-Jan-2016         109  
    03-Feb-2016      107.82  
    03-Mar-2016      113.17  
    03-Apr-2016      128.01  
    03-May-2016         116  

Determine if M is a regular timetable.

tf = isregular(M)

tf = logical
   0

M is not regular with respect to time because the first five months have different numbers of days. Therefore, the exact amount of time between consecutive row times differs from row to row. You can use the diff function to calculate the differences in the time steps between consecutive times in M. The differences are duration values, formatted to display the time steps as hours, minutes, and seconds.

T = diff(M.Time)

T = 4x1 duration
   744:00:00
   696:00:00
   744:00:00
   720:00:00

M is regular with respect to months because the time interval between the row times of M is always one calendar month.

tf = isregular(M,'months')

tf = logical
   1

Determine Time Step of Row Times

Create a timetable. Determine if it is regular, and then return the size of the time step if it is.

Time = [minutes(0):minutes(15):minutes(60)]';
Pulse = [72 75 80 73 69]';
TT = timetable(Time,Pulse)

TT=5×1 timetable
     Time     Pulse
    ______    _____

    0 min      72  
    15 min     75  
    30 min     80  
    45 min     73  
    60 min     69  

[TF,dt] = isregular(TT)

TF = logical
   1

dt = duration
   15 min

TT is a regular timetable.

Input Arguments

D — Input variable

timetable | datetime vector | duration vector

Input variable, specified as a timetable, a datetime vector, or a duration vector.

timeUnit — Time or calendar unit

character vector | string scalar

Time or calendar unit, specified as a character vector or string scalar. isregular determines if the consecutive times of D are regular to the time or calendar unit specified by timeUnit. The table lists the units that you can specify.

Time or Calendar Unit	Description
'years'	Regular to the year
'quarters'	Regular to the quarter
'months'	Regular to the month
'weeks'	Regular to the week
'days'	Regular to the day
'time' (default)	Regular with respect to time

• If D is a datetime vector or a timetable whose row times are datetime values, then the time steps might be regular with respect to a calendar unit such as months, but irregular with respect to exact elapsed time.

  For example, if the times are regular monthly datetime values, and timeUnit is 'month', then isregular returns 1. But if timeUnit is 'time', then isregular returns 0 because different months can represent different lengths of time.

• If D is a duration vector or a timetable whose row times are duration values, then specify timeUnit as 'time' or use the first syntax. The duration data type does not represent times using calendar units.

Output Arguments

tf — True or false

1 | 0

True or false, returned as a logical 1 if the input is regular and a logical 0 if it is not.

dt — Time step between consecutive times

duration scalar | calendarDuration scalar

Time step between consecutive times, returned as a duration or calendarDuration scalar. If the input is not regular, then dt is a NaN value.

Tips

• In certain cases, you can create a timetable or datetime vector while specifying a regular time step, and yet the result is irregular. Such a result can occur when you specify the time step by using a calendar unit of time and there is a time that introduces an irregular step. For example, if you create a timetable with a time step of one calendar month, starting on January 31, 2019, then it is irregular with respect to months.

  stime = datetime(2019,1,31);
  tstep = calmonths(1);
  TT = timetable('Size',[3 1],'VariableTypes',{'double'},...
                 'TimeStep',tstep,'StartTime',stime);
  tf = isregular(TT,'month')
  

  tf =
  
    logical
  
     0
  

• There are other cases where irregularities are due to shifts from Daylight Saving Time (DST) or to datetime values that are leap seconds. This table specifies the dates, times, and time steps that can produce irregular results unexpectedly.

  Row Time Value	Time Step
  Start time specified as the 29th, 30th, or 31st day of the month.	Number of calendar months or quarters.
  Start time specified as February 29.	Number of calendar years.
  Any datetime value occurring between 1:00 a.m. and 2:00 a.m. on a day shifting from DST to standard time (when such values have a time zone that observes DST).	Number of calendar days or months.
  Any datetime value that is a leap second (when the time zone for such values is the UTCLeapSeconds time zone). For the list of leap seconds, see leapseconds.	Time step specified in any calendar unit (days, weeks, months, quarters, or years).

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The isregular function fully supports tall arrays. For more information, see Tall Arrays.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The input argument timeUnit must be constant. To make it constant, use the coder.Constant function.

• timeUnit cannot be a calendar unit. If you specify it, then its value must be 'time'.

For more information, see Code Generation for Timetables (MATLAB Coder) and Timetable Limitations for Code Generation (MATLAB Coder).

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2016b

R2021b: Support for datetime and duration data types

You can use the isregular function to determine if a timetable, datetime vector, or duration vector is regular. In previous releases, you can use isregular only on a timetable.