containsrange

Determine if timetable row times contain specified time range

Since R2020a

Syntax

tf = containsrange(TT,rangeOfTimes)

tf = containsrange(TT,oneTime)

[tf,whichRows] = containsrange(___)

Description

tf = containsrange(TT,rangeOfTimes) returns 1 (true) if the range of the row times of TT contains 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.

tf = containsrange(TT,oneTime) determines if the range of row times of TT contains the time specified by oneTime.

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

Examples

Determine If Timetable Contains Time Range

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 0.1–0.35 seconds. To create the object, use the timerange function. Its inputs are durations, which you can create using the seconds function.

rangeOfTimes = timerange(seconds(0.1),seconds(0.35))

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.35 sec

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

tf = containsrange(TT,rangeOfTimes)

tf = logical
   1

Create another time range object with a range of 0.1–0.9 seconds. For this range, the containsrange function returns 0, because 0.9 seconds is outside the time range of TT.

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 = containsrange(TT,rangeOfTimes)

tf = logical
   0

Compare Time Ranges of Timetables

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];
TT2 = timetable(Readings,'TimeStep',seconds(0.15),'StartTime',seconds(0.05))

TT2=3×1 timetable
      Time      Readings
    ________    ________

    0.05 sec       74   
    0.2 sec        83   
    0.35 sec       99   

Determine if the range of row times in TT1 contains the range of row times in TT2.

tf = containsrange(TT1,TT2)

tf = logical
   1

And on the other hand, the range of row times of TT2 does not contain the range of TT1.

tf = containsrange(TT2,TT1)

tf = logical
   0

Determine If Timetable Contains Time

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

Determine if the range of row times in TT contains oneTime.

tf = containsrange(TT,oneTime)

tf = logical
   1

oneTime does not have to match a specific row time of TT. If oneTime is any time between the minimum and maximum row times of TT, then containsrange returns 1.

oneTime = datetime('2018-02-28 09:23:45')

oneTime = datetime
   28-Feb-2018 09:23:45

tf = containsrange(TT,oneTime)

tf = logical
   1

Find Rows Within Time Range

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 row whose row time is not.

rangeOfTimes = timerange(seconds(0.1),seconds(0.35));
[tf,whichRows] = containsrange(TT,rangeOfTimes)

tf = logical
   1

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

TT — Input timetable

timetable

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

rangeOfTimes — Time range

time range object | timetable

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 containsrange 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. containsrange gets them automatically from the minimum and maximum row times of the timetable.

oneTime — Single time

datetime scalar | duration scalar

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

Output Arguments

tf — True or false

1 | 0

True or false, returned as a logical 1 if the range of the row times of TT contains the time range specified by rangeOfTimes or the point in time specified by oneTime, and a logical 0 otherwise.

whichRows — Indices of rows within specified time range

logical array

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

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2020a

R2023b: Specify time range that uses event filters

When you call containsrange, 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 using containsrange with event filters, see eventfilter.