Main Content

withinrange

Determine if timetable row times are within specified time range

Since R2020a

collapse all in page

Syntax

tf = withinrange(TT,rangeOfTimes)
tf = withinrange(TT,oneTime)
[tf,whichRows] = withinrange(___)

Description

tf = withinrange(TT,rangeOfTimes) returns 1 (true) if the range of the row times of TT is entirely within the time range specified by rangeOfTimes. Otherwise, it returns 0 (false).

The range of the row times of TT is determined by its minimum and maximum row times.

example

tf = withinrange(TT,oneTime) returns 1 if the row times of TT are all the same and all equal to the time specified by oneTime.

example

[tf,whichRows] = withinrange(___) also returns logical indices indicating which rows of TT are within the specified time range.

example

Examples

collapse all

Open Live Script

Create a timetable whose row times range from 0 seconds to 0.4 seconds.

Intensity = [100;98.7;95.2;101.4;99.1];
TT = timetable(Intensity,'TimeStep',seconds(0.1))
TT=5×1 timetable
     Time      Intensity
    _______    _________

    0 sec          100  
    0.1 sec       98.7  
    0.2 sec       95.2  
    0.3 sec      101.4  
    0.4 sec       99.1

Create a time range object with a range of –1 to 1 seconds. To create the object, use the timerange function. Its inputs are durations, which you can create using the seconds function.

rangeOfTimes = timerange(seconds(-1),seconds(1))
rangeOfTimes = 
	timetable timerange subscript:

		Select timetable rows with times in the half-open interval:
		  Starting at, including:   -1 sec
		  Ending at, but excluding: 1 sec

Determine if the row times of TT are within the range specified by rangeOfTimes.

tf = withinrange(TT,rangeOfTimes)
tf = logical
   1

Create another time range object with a range of 0.1–0.9 seconds. The withinrange function returns 0 because the first row time of TT is not within rangeOfTimes.

rangeOfTimes = timerange(seconds(0.1),seconds(0.9))
rangeOfTimes = 
	timetable timerange subscript:

		Select timetable rows with times in the half-open interval:
		  Starting at, including:   0.1 sec
		  Ending at, but excluding: 0.9 sec


tf = withinrange(TT,rangeOfTimes)
tf = logical
   0
Open Live Script

Create two timetables with different time ranges. The timetables can also have different variables and different numbers of rows.

Intensity = [100;98.7;95.2;101.4;99.1];
TT1 = timetable(Intensity,'TimeStep',seconds(0.1))
TT1=5×1 timetable
     Time      Intensity
    _______    _________

    0 sec          100  
    0.1 sec       98.7  
    0.2 sec       95.2  
    0.3 sec      101.4  
    0.4 sec       99.1  


Readings = [74;83;99;75;87;93;92];
TT2 = timetable(Readings,'TimeStep',seconds(0.1),'StartTime',seconds(-0.1))
TT2=7×1 timetable
      Time      Readings
    ________    ________

    -0.1 sec       74   
    0 sec          83   
    0.1 sec        99   
    0.2 sec        75   
    0.3 sec        87   
    0.4 sec        93   
    0.5 sec        92

Determine if the range of row times in TT1 is within the range of row times in TT2.

tf = withinrange(TT1,TT2)
tf = logical
   1

And on the other hand, the range of row times of TT2 is not within the range of TT1.

tf = withinrange(TT2,TT1)
tf = logical
   0
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 point in time using the datetime function. This time is midnight on February 1, 2018.

oneTime = datetime('2018-02-01')
oneTime = datetime
   01-Feb-2018

Compare the row times of TT to oneTime. While one row time happens to be equal to oneTime, the other row times are not equal. Therefore, the withinrange function returns 0.

tf = withinrange(TT,oneTime)
tf = logical
   0

Timetables can have duplicate row times. Change all the row times of TT to the same value, and call withinrange again. Now, all row times are equal to oneTime, and withinrange returns 1.

TT.Time(1:end) = oneTime
TT=6×1 timetable
       Time        Price
    ___________    _____

    01-Feb-2018     106 
    01-Feb-2018     108 
    01-Feb-2018      88 
    01-Feb-2018     108 
    01-Feb-2018     101 
    01-Feb-2018      87 


tf = withinrange(TT,oneTime)
tf = logical
   1
Open Live Script

Create a timetable.

Intensity = [100;98.7;95.2;101.4;99.1];
TT = timetable(Intensity,'TimeStep',seconds(0.1))
TT=5×1 timetable
     Time      Intensity
    _______    _________

    0 sec          100  
    0.1 sec       98.7  
    0.2 sec       95.2  
    0.3 sec      101.4  
    0.4 sec       99.1

Specify a time range. Then determine which rows of TT are within the time range. The second output argument, whichRows, is a logical array whose elements correspond to the rows of TT. It contains 1 for each row whose row time is within the time range, and 0 for each whose row time is not.

rangeOfTimes = timerange(seconds(0.1),seconds(0.35));
[tf,whichRows] = withinrange(TT,rangeOfTimes)
tf = logical
   0


whichRows = 5x1 logical array

   0
   1
   1
   1
   0

To access the rows within the time range, index into TT using whichRows.

TT2 = TT(whichRows,:)
TT2=3×1 timetable
     Time      Intensity
    _______    _________

    0.1 sec       98.7  
    0.2 sec       95.2  
    0.3 sec      101.4

Input Arguments

collapse all

Input timetable. The minimum and maximum row times of TT determine its range of times.

Time range, specified as a time range object or a timetable.

  • If you specify rangeOfTimes as a time range object, then create the time range using the timerange function. Specify the beginning and end times of the range explicitly as inputs to timerange.

    • If the input timetable TT has an attached event table, then you can call withinrange with a time range object that uses event filters. For more information on specifying a time range using event filters, see eventfilter (since R2023b)

  • If you specify rangeOfTimes as a timetable, then you do not need to specify the beginning and end of the range explicitly. withinrange gets them automatically from the minimum and maximum row times of the timetable.

A single time, specified as a datetime or duration scalar.

Output Arguments

collapse all

True or false, returned as a logical 1 if the range of the row times of TT is entirely within the time range specified by rangeOfTimes, and a logical 0 otherwise.

Indices of the rows within the specified time range, returned as a logical array. You can index into TT using whichRows.

For example, in this code you can use the second output of withinrange to index into the timetable TT. The timetable TT2 includes only those rows whose row times are within the range specified by rangeOfTimes.

[tf,whichVars] = (TT,rangeOfTimes);
TT2 = T(whichRows,:)

Extended Capabilities

Version History

Introduced in R2020a

expand all

See Also

| | | | | | |

Topics