timerange - Time range for timetable row subscripting - MATLAB (original) (raw)

Time range for timetable row subscripting

Syntax

Description

S = timerange([startTime,endTime](#bvdk6vh-startTimeendTime)) 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 useS to subscript into a timetable whose row times are duration values.

example

S = timerange([startTime,endTime](#bvdk6vh-startTimeendTime),[intervalType](#bvdk6vh-intervalType)) creates a subscript over the type of interval specified byintervalType. For example, ifintervalType is 'closed', thenS includes both startTime andendTime in the time range it specifies.

example

S = timerange([startPeriod,endPeriod](#mw%5F089f69b1-cc6c-4f37-8fc1-83bd12e27e9b),[datetimeUnit](#mw%5F6f96b46a-c404-4d32-902b-db9bbd968928)) creates a subscript over the time period between startPeriod and endPeriod, using the date or time component specified bydatetimeUnit. For example, ifdatetimeUnit is 'months', thenS includes the start of the month that is a component ofstartPeriod, and the end of the month ofendPeriod. The inputs startPeriod andendPeriod can be datetime scalars, or if text, they can be character vectors or strings that specify dates and times.

example

S = timerange([timePeriod](#mw%5F9618d26e-1982-41f6-8db7-c922a41ea19a),[datetimeUnit](#mw%5F6f96b46a-c404-4d32-902b-db9bbd968928)) creates a subscript spanning the beginning and end oftimePeriod, using the date or time component specified bydatetimeUnit. For example, ifdatetimeUnit is 'day', thenS includes the start and end of the day that is a component of timePeriod. The inputtimePeriod can be a datetime scalar, or if text, it can be a character vector or string that specifies a time period.

example

S = timerange([startEF,endEF](#mw%5F1312b15e-c4d0-47ab-a206-50a31c2e616b)) 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

collapse all

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=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=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.

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.

ans=2×1 timetable Time Price ___________ _____

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

Input Arguments

collapse all

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. IfstartTime 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 ofdatetime or duration.

To create one-sided time ranges, use '-inf' or'inf' as start or end times. The syntaxtimerange('-inf',endTime) specifies all dates and times before endTime, whiletimerange(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.

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. IfstartPeriod 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 ofdatetime.

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 ofstartPeriod.

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 thedatetime 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 specifydatetimeUnit only when the other input arguments specify datetime values, and not duration values.

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 bystartEF and the latest event matched byendEF.

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

expand all

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.