# 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

example

````tf = isregular(D)` returns `1` (`true`) if `D` is regular with respect to time. Otherwise, it returns `0` (`false`). The input `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.`duration` vector.Timetable. It is regular if its vector of row times is regular. This syntax is equivalent to `isregular(D,'time')`.```

example

````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'`.```

example

``````[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

collapse all

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 ```

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 ```

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

collapse all

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

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

collapse all

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

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

Introduced in R2016b