withtol

R2026b

Time tolerance for timetable row subscripting

Syntax

S = withtol(rowTimes,tol)

S = withtol(EF,tol)

Description

S = withtol(rowTimes,tol) creates a subscript to select rows of a timetable. S selects all rows whose row times match a time in rowTimes within the tolerance specified by tol. The rowTimes argument is a datetime, duration, or numeric (double or single) array, or a cell array of character vectors that specify dates and times. tol must be a nonnegative duration or numeric value.

rowTimes must match the type of the timetable row times:

• If rowTimes contains datetime (or text representing datetimes) values, then you only can use S to subscript into a timetable with datetime row times.

• If rowTimes contains duration values, then you only can use S to subscript into a timetable with duration row times.

• If rowTimes contains numeric values, then you only can use S to subscript into a timetable with numeric row times.

S = withtol(EF,tol) creates a row subscript using an event filter. To use event filters, the timetable you subscript into must have an attached event table. For more information on specifying a time tolerance using event filters, see eventfilter. (since R2023a)

Examples

Specify Tolerance to Match Row Times

Create a timetable that contains temperature and pressure data with row times in hours. There is a slight random variance in the row times. Select rows with row times that match corresponding times in a time vector within a tolerance of five seconds.

Time = datetime(2015,12,18) + hours(1:10)' + seconds(randn(10,1));
Temp = [37.3 39.1 42.3 42.6 43 43.9 44.1 43.3 42.5 42]';
Pressure = [29.4 29.6 30.0 30.0 30.1 29.9 29.9 29.8 29.6 29.7]';
TT = timetable(Time,Temp,Pressure)

TT = 10×2 timetable
            Time            Temp    Pressure
    ____________________    ____    ________

    18-Dec-2015 01:00:00    37.3      29.4  
    18-Dec-2015 02:00:01    39.1      29.6  
    18-Dec-2015 02:59:57    42.3        30  
    18-Dec-2015 04:00:00    42.6        30  
    18-Dec-2015 05:00:00      43      30.1  
    18-Dec-2015 05:59:58    43.9      29.9  
    18-Dec-2015 06:59:59    44.1      29.9  
    18-Dec-2015 08:00:00    43.3      29.8  
    18-Dec-2015 09:00:03    42.5      29.6  
    18-Dec-2015 10:00:02      42      29.7  

Create a time vector spanning the hours from 3:00 to 8:00.

newTimes = datetime(2015,12,18) + hours(3:8)

newTimes = 1×6 datetime
   18-Dec-2015 03:00:00   18-Dec-2015 04:00:00   18-Dec-2015 05:00:00   18-Dec-2015 06:00:00   18-Dec-2015 07:00:00   18-Dec-2015 08:00:00

Select rows of TT with row times that match times in newTimes within five seconds.

S = withtol(newTimes,seconds(5));
TT2 = TT(S,:)

TT2 = 6×2 timetable
            Time            Temp    Pressure
    ____________________    ____    ________

    18-Dec-2015 02:59:57    42.3        30  
    18-Dec-2015 04:00:00    42.6        30  
    18-Dec-2015 05:00:00      43      30.1  
    18-Dec-2015 05:59:58    43.9      29.9  
    18-Dec-2015 06:59:59    44.1      29.9  
    18-Dec-2015 08:00:00    43.3      29.8  

Input Arguments

rowTimes — Times to match in timetable

datetime array | duration array | double array | single array | cell array of character vectors | string array

Times to match in a timetable, specified as a datetime array, duration array, double array, single array, cell array of character vectors, or string array. rowTimes contains times that do not exactly match times in the row times of a timetable, but that might be within a specified tolerance.

If rowTimes is a cell array of character vectors or string array, then the elements of the array specify dates and times that the datetime or duration functions can convert.

tol — Tolerance for matching times to row times of timetable

duration scalar | double scalar | single scalar | character vector | string scalar

Tolerance for matching times to the row times of a timetable, specified as a duration scalar, double scalar, single scalar, character vector, or string scalar. The tolerance value cannot be less than zero.

If tol is a character vector or string scalar, then tol specifies a time that the duration function can convert.

You must specify tol as a numeric scalar if rowTimes is a numeric array

EF — event filter

event filter

Since R2023a

Event filter.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• Event filters are not supported.

For more information, see Code Generation for Timetables (MATLAB Coder) and Timetable Limitations for Code Generation (MATLAB Coder).

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

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

Version History

Introduced in R2016b

R2026b: withtol now supports numeric row times

The withtol function now supports numeric (double or single) arrays as rowTimes and numeric tolerance values. Previously, withtol supported only datetime, duration or text values. This allows you to create tolerance-based subscripts for timetables with numeric row times.

R2023a: Specify time tolerance that uses an event filter

When you call withtol, you can specify a time tolerance that find rows around the events found by an event filter. 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.

R2023a: Improved performance when subscripting into timetable with withtol subscript

timetable subscripting when subscripting with a withtol subscript is significantly faster in R2023a than in R2022b.

• When you use a withtol subscript with a timetable that has 10⁷ rows, performance in R2023a is about 44x faster than in R2022b.

  function timingTest()
  rng default
  
  % 10^7 rows
  N = 10000000;
  rowtimes = seconds(0:N-1);
  tt = timetable(rand(N,1),RowTimes=rowtimes);
  
  % 100 values chosen in steps of 10
  n = 1000;
  t = seconds(0:10:n-1);
  
  tt.Time = tt.Time + .1*seconds(rand(N,1));
  wt = withtol(t,seconds(.1));
      
  tic
  tt2 = tt(wt,:);
  toc
  end
  

  The approximate execution times are:

  R2022b: 3.92 s

  R2023a: 0.09 s

The code was timed on a Windows^® 10, AMD^® EPYC 74F3 24-Core Processor @ 3.19 GHz test system by calling each version of the timingTest function.