timerange

Time range for timetable row subscripting

Syntax

S = timerange(startTime,endTime)

S = timerange(startTime,endTime,intervalType)

S = timerange(startPeriod,endPeriod,datetimeUnit)

S = timerange(timePeriod,datetimeUnit)

S = timerange(startEF,endEF)

Description

S = timerange(startTime,endTime) creates a subscript to select rows of a timetable within a range of times. S selects all rows whose times are in the time interval specified by startTime and endTime, including startTime but not endTime. In other words, the time interval is a half-open interval. startTime and endTime are datetime or duration scalars, or character vectors or strings that specify dates and times.

If startTime and endTime are datetime values, then you only can use S to subscript into a timetable whose row times are datetime values. Similarly, if startTime and endTime are duration values, then you only can use S to subscript into a timetable whose row times are duration values.

S = timerange(startTime,endTime,intervalType) creates a subscript over the type of interval specified by intervalType. For example, if intervalType is 'closed', then S includes both startTime and endTime in the time range it specifies.

S = timerange(startPeriod,endPeriod,datetimeUnit) creates a subscript over the time period between startPeriod and endPeriod, using the date or time component specified by datetimeUnit. For example, if datetimeUnit is 'months', then S includes the start of the month that is a component of startPeriod, and the end of the month of endPeriod. The inputs startPeriod and endPeriod can be datetime scalars, or if text, they can be character vectors or strings that specify dates and times.

S = timerange(timePeriod,datetimeUnit) creates a subscript spanning the beginning and end of timePeriod, using the date or time component specified by datetimeUnit. For example, if datetimeUnit is 'day', then S includes the start and end of the day that is a component of timePeriod. The input timePeriod can be a datetime scalar, or if text, it can be a character vector or string that specifies a time period.

S = timerange(startEF,endEF) creates a row subscript using a pair of event filters. To use event filters, the timetable you subscript into must have an attached event table. For more information on specifying a time range using event filters, see eventfilter. (since R2023a)

Examples

Select Timetable Rows in Specified Time Interval

Create a timetable that contains times along with measurements of temperature, pressure, and wind speed and direction. Select rows whose times fall within a specified time interval.

Time = datetime({'12/18/2015 08:00:00';'12/18/2015 10:00:0';'12/18/2015 12:00:00';...
                 '12/18/2015 14:00:00';'12/18/2015 16:00:00';'12/18/2015 18:00:00'});
Temp = [37.3;39.1;42.3;45.7;41.2;39.9];
Pressure = [30.1;30.03;29.9;29.8;30.0;29.9];
WindSpeed = [13.4;6.5;7.3;8.5;9.2;4.3];
WindDirection = categorical({'NW';'N';'NW';'NW';'NNW';'N'});
TT = timetable(Time,Temp,Pressure,WindSpeed,WindDirection)

TT=6×4 timetable
            Time            Temp    Pressure    WindSpeed    WindDirection
    ____________________    ____    ________    _________    _____________

    18-Dec-2015 08:00:00    37.3      30.1        13.4            NW      
    18-Dec-2015 10:00:00    39.1     30.03         6.5            N       
    18-Dec-2015 12:00:00    42.3      29.9         7.3            NW      
    18-Dec-2015 14:00:00    45.7      29.8         8.5            NW      
    18-Dec-2015 16:00:00    41.2        30         9.2            NNW     
    18-Dec-2015 18:00:00    39.9      29.9         4.3            N       

Specify a time range between 12/18/2015 08:00:00 and 12/18/2015 12:00:00.

S = timerange('12/18/2015 08:00:00','12/18/2015 12:00:00')

S = 
	timetable timerange subscript:

		Select timetable rows with times in the half-open interval:
		  Starting at, including:   18-Dec-2015 08:00:00
		  Ending at, but excluding: 18-Dec-2015 12:00:00

Select rows with times in the range specified by S. The output timetable includes the start of the time range, but not the end.

TT2 = TT(S,:)

TT2=2×4 timetable
            Time            Temp    Pressure    WindSpeed    WindDirection
    ____________________    ____    ________    _________    _____________

    18-Dec-2015 08:00:00    37.3      30.1        13.4            NW      
    18-Dec-2015 10:00:00    39.1     30.03         6.5            N       

Select Timetable Rows in Closed Time Interval

Create a timetable.

Time = [seconds(1):seconds(1):seconds(5)];
TT = timetable(Time',[98;97.5;97.9;98.1;97.9],[120;111;119;117;116],...
               'VariableNames',{'Reading1','Reading2'})

TT=5×2 timetable
    Time     Reading1    Reading2
    _____    ________    ________

    1 sec        98        120   
    2 sec      97.5        111   
    3 sec      97.9        119   
    4 sec      98.1        117   
    5 sec      97.9        116   

Specify a closed time interval between two and four seconds.

S = timerange(seconds(2),seconds(4),'closed')

S = 
	timetable timerange subscript:

		Select timetable rows with times in the closed interval:
		  Starting at, including: 2 sec
		  Ending at, including:   4 sec

Select rows with times in the range specified by S. The closed interval includes both the start and end times.

TT2 = TT(S,:)

TT2=3×2 timetable
    Time     Reading1    Reading2
    _____    ________    ________

    2 sec      97.5        111   
    3 sec      97.9        119   
    4 sec      98.1        117   

Specify Time Period

Create a timetable containing prices set at the middle of each month.

Time = datetime(2018,1:12,15)';
Price = randi([85 110],12,1);
TT = timetable(Time,Price)

TT=12×1 timetable
       Time        Price
    ___________    _____

    15-Jan-2018     106 
    15-Feb-2018     108 
    15-Mar-2018      88 
    15-Apr-2018     108 
    15-May-2018     101 
    15-Jun-2018      87 
    15-Jul-2018      92 
    15-Aug-2018      99 
    15-Sep-2018     109 
    15-Oct-2018     110 
    15-Nov-2018      89 
    15-Dec-2018     110 

Specify a time range using 'quarters' as the unit of time. The start of the time range is the quarter that includes January 1, 2018. The end of the range is the quarter that includes May 1, 2018. The time range includes whole quarters, meaning that the end of the range is the instant before the start of July 1, 2018.

S = timerange('2018-01-01','2018-05-01','quarters')

S = 
	timetable timerange subscript:

		Select timetable rows with times in the half-open interval:
		  Starting at, including:   01-Jan-2018 00:00:00
		  Ending at, but excluding: 01-Jul-2018 00:00:00

Select rows of TT. The output timetable includes the rows for May 15 and June 15, 2018, but not the row for July 15, or any row with a time outside the first two quarters of 2018.

TT(S,:)

ans=6×1 timetable
       Time        Price
    ___________    _____

    15-Jan-2018     106 
    15-Feb-2018     108 
    15-Mar-2018      88 
    15-Apr-2018     108 
    15-May-2018     101 
    15-Jun-2018      87 

Specify Time Period from One Date

Create a timetable containing prices set at the beginning and middle of each month.

Time = datetime({'2018-01-01';'2018-01-15';'2018-02-01';'2018-02-15';
                 '2018-03-01';'2018-03-15'});
Price = randi([85 110],6,1);
TT = timetable(Time,Price)

TT=6×1 timetable
       Time        Price
    ___________    _____

    01-Jan-2018     106 
    15-Jan-2018     108 
    01-Feb-2018      88 
    15-Feb-2018     108 
    01-Mar-2018     101 
    15-Mar-2018      87 

Specify a time range using 'months' as the unit of time. As the first input is a date in February, 2018, the time range spans the whole month of February.

S = timerange('2018-02-01','months')

S = 
	timetable timerange subscript:

		Select timetable rows with times in the half-open interval:
		  Starting at, including:   01-Feb-2018 00:00:00
		  Ending at, but excluding: 01-Mar-2018 00:00:00

Select rows of TT.

TT(S,:)

ans=2×1 timetable
       Time        Price
    ___________    _____

    01-Feb-2018      88 
    15-Feb-2018     108 

Input Arguments

startTime,endTime — Start and end times of time range

pair of datetime scalars | pair of duration scalars | pair of character vectors | pair of string scalars

Start and end times of time range, specified as a pair of datetime or duration scalars, or as a pair of character vectors or string scalars.

If startTime and endTime are character vectors or string scalars, then they specify dates and times. If startTime and endTime have formats that timerange does not recognize, then convert them to datetime or duration values using the datetime or duration function. Specify the format using the 'InputFormat' argument of datetime or duration.

To create one-sided time ranges, use '-inf' or 'inf' as start or end times. The syntax timerange('-inf',endTime) specifies all dates and times before endTime, while timerange(startTime,'inf') specifies all dates and times after startTime.

intervalType — Type of time range interval

'openright' (default) | 'closedleft' | 'openleft' | 'closedright' | 'open' | 'closed'

Type of time range interval, specified as one of the interval types listed in the table.

Interval Type	Description
'openright' (default)	Select rows with times that satisfy the half-open interval startTime <= rowTime and rowTime < endTime.
'closedleft'	Equivalent to 'openright'.
'openleft'	Select rows with times that satisfy the half-open interval startTime < rowTime and rowTime <= endTime.
'closedright'	Equivalent to 'openleft'.
'open'	Select rows with times that satisfy the open interval startTime < rowTime and rowTime < endTime.
'closed'	Select rows with times that satisfy the closed interval startTime <= rowTime and rowTime <= endTime.

startPeriod,endPeriod — Start and end time periods

pair of datetime scalars | pair of character vectors | pair of string scalars

Start and end time periods, specified as a pair of datetime scalars, or as a pair of character vectors or string scalars.

If startPeriod and endPeriod are character vectors or string scalars, then they specify dates and times. If startPeriod and endPeriod have formats that timerange does not recognize, then convert them to datetime values using the datetime function. Specify the format using the 'InputFormat' argument of datetime.

To create one-sided time ranges, use '-inf' or 'inf' as start or end periods. For example, the syntax timerange('-inf',endPeriod,'days') specifies all dates and times before the end of the day of endPeriod. The syntax timerange(startTime,'inf','days') specifies all dates and times after the start of the day of startPeriod.

timePeriod — Time period

datetime scalar | character vector | string scalar

Time period, specified as a datetime scalar, character vector, or string scalar. If timePeriod is a character vector or a string scalar, then it specifies a date and time that the datetime function can convert into a datetime value.

datetimeUnit — Component of time periods

'years' | 'quarters' | 'months' | 'weeks' | 'days''hours' | 'minutes' | 'seconds'

Component of time periods, specified as one of the date or time components listed in the table.

Note: You can specify datetimeUnit only when the other input arguments specify datetime values, and not duration values.

Date or Time Component	Description
'years'	Select rows with times such that year(startPeriod) <= year(rowTime) and year(rowTime) <= year(endPeriod).
'quarters'	Select rows with times such that quarter(startPeriod) <= quarter(rowTime) and quarter(rowTime) <= quarter(endPeriod).
'months'	Select rows with times such that month(startPeriod) <= month(rowTime) and month(rowTime) <= month(endPeriod).
'weeks'	Select rows with times such that week(startPeriod) <= week(rowTime) and week(rowTime) <= week(endPeriod).
'days'	Select rows with times such that day(startPeriod) <= day(rowTime) and day(rowTime) <= day(endPeriod).
'hours'	Select rows with times such that hour(startPeriod) <= hour(rowTime) and hour(rowTime) <= hour(endPeriod).
'minutes'	Select rows with times such that minute(startPeriod) <= minute(rowTime) and minute(rowTime) <= minute(endPeriod).
'seconds'	Select rows with times such that second(startPeriod) <= second(rowTime) and second(rowTime) <= second(endPeriod).

startEF,endEF — Start and end event filters

pair of event filters

Since R2023a

Start and end event filters, specified as a pair of event filters.

If startEF or endEF match multiple events, then the time range spans the earliest event matched by startEF and the latest event matched by endEF.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• The input argument datetimeUnit is not supported.

• Event filters are not supported.

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.

Version History

Introduced in R2016b

R2023a: Specify time range that uses event filters

When you call timerange, you can specify a time range that uses event filters as its start and end times. To use event filters, you must first attach an event table to the input timetable. For more information on event tables and event filters, see eventtable and eventfilter.