timerange

Time range for timetable row subscripting

collapse all in page

Syntax

S = timerange(startTime,endTime)
S = timerange(startTime,endTime,intervalType)
S = timerange(startPeriod,endPeriod,unitOfTime)
S = timerange(timePeriod,unitOfTime)

Description

example

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.

example

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.

example

S = timerange(startPeriod,endPeriod,unitOfTime) creates a subscript over the time period between startPeriod and endPeriod, using the date or time component specified by unitOfTime. For example, if unitOfTime 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.

example

S = timerange(timePeriod,unitOfTime) creates a subscript spanning the beginning and end of timePeriod, using the date or time component specified by unitOfTime. For example, if unitOfTime is 'day', then S includes the start and end of the day that is a component of timePeriod.

Examples

collapse all

Open Live Script

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:
		[18-Dec-2015 08:00:00, 18-Dec-2015 12:00:00)

	See Select Timetable Data by Row Time and Variable Type.

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
Open Live Script

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:
		[2 sec, 4 sec]

	See Select Timetable Data by Row Time and Variable Type.

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
Open Live Script

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: QUARTERS
		  Starting at, including:   01-Jan-2018 00:00:00
		  Ending at, but excluding: 01-Jul-2018 00:00:00

	See Select Timetable Data by Row Time and Variable Type.

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
Open Live Script

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: MONTHS
		  Starting at, including:   01-Feb-2018 00:00:00
		  Ending at, but excluding: 01-Mar-2018 00:00:00

	See Select Timetable Data by Row Time and Variable Type.

Select rows of TT.

TT(S,:)
ans=2×1 timetable
       Time        Price
    ___________    _____

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

Input Arguments

collapse all

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.

Type of time range interval, specified as a character vector or string scalar. The table shows the types of time range intervals.

Interval Type

Description

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

'openleft'

Select rows with times that satisfy the half-open interval startTime < rowTime and rowTime <= endTime.

'openright' (default)

Select rows with times that satisfy the half-open interval startTime <= rowTime and rowTime < endTime.

'closedright'

Equivalent to 'openleft'.

'closedleft'

Equivalent to 'openright'.

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.

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.

Component of time periods, specified as a character vector or string scalar. The table shows the components that you can specify.

Note: You can specify unitOfTime 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).

Extended Capabilities

See Also

| | | | | |

Topics

Introduced in R2016b

MATLAB Documentation

Support