isregular

Determine whether times in timetable are regular

Description

example

TF = isregular(TT) returns 1 (true) if the row times in the timetable TT are regular. Otherwise, it returns 0 (false). The row times are regular if they increase or decrease monotonically by a fixed time step. For example, if consecutive row times always differ by one second, then the times are regular.

example

TF = isregular(TT,unit) returns 1 (true) if the row times are regular with respect to the calendar duration unit specified by unit. For example, if the row times are datetime values whose year and month components are regular to the month, and unit is 'month', then isregular returns 1.

example

[TF,dt] = isregular(___) also returns dt, the fixed time step between row times. If TT is regular, then dt is either a duration or a calendar duration. If TT is not regular, then dt is a NaN value.

Examples

collapse all

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

Create a timetable whose row times are the first five months of the year 2016. Add the monthly price of a stock as a table variable.

StockPrice = [109.0;107.82;113.17;128.01;116];
M = timetable(datetime(2016,1:5,3)',StockPrice)
M=5×2 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 whether M is a regular timetable.

TF = isregular(M)
TF = logical
   0

M is not regular because the first five months have different numbers of days. You can use the diff function to calculate the differences in the time steps between consecutive times in M. The differences are durations, formatted to display the time steps as hours, minutes, and seconds.

D = diff(M.Time)
D = 4x1 duration array
   744:00:00
   696:00:00
   744:00:00
   720:00:00

Determine whether M is regular with respect to months, by specifying 'month' as the unit of measure.

TF = isregular(M,'months')
TF = logical
   1

Create a timetable. Determine if it is regular, and 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×2 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

collapse all

Input timetable.

Calendar duration unit, specified as a character vector or string scalar. isregular determines if the row times of TT are regular to the calendar unit specified by unit. The table lists the calendar duration units you can specify.

Time 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

Output Arguments

collapse all

Regularity of row times, returned as a logical 1 if the row times are regular, and a logical 0 if they are not.

Time step between row times, returned as a duration or a calendar duration. If the timetable is not regular, then dt is a NaN value.

Tips

  • In certain cases, you can create a timetable while specifying a regular time step between row times, and yet the resulting timetable is irregular. This result occurs when you specify the time step using a calendar unit of time and there is a row 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
    

    In addition, there are other cases where irregularities are due to shifts from Daylight Saving Time (DST) or to row times that are leap seconds. This table specifies the row time values and time steps that can produce irregular timetables 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 row time occurring between 1:00 a.m. and 2:00 a.m. on a day shifting from DST to standard time (when row times are specified as datetime values whose time zone observes DST)Number of calendar days or months

    Any row time that is a leap second (when row times are specified as datetime values whose time zone is the UTCLeapSeconds time zone)

    Time step specified in any calendar unit (days, weeks, months, quarters, or years)

Extended Capabilities

Introduced in R2016b