eventtable
datatypes: eventtable
Timetable of events, describing what was happening rather than what was measured.
An event table is a timetable whose rows are events. Each row has
a time, optionally a label naming the event, and optionally a length or
an end time making it an interval rather than an instant. It exists so
that the rows of another timetable can be selected by what was happening
when they were recorded, rather than by the clock alone.
An event table is a timetable and inherits every one of its
methods. help does not follow method inheritance, so
help eventtable.sortrows does not resolve and
help timetable.sortrows is where that method is documented; where
a method behaves differently for an event table, its own documentation
says so.
Three properties say which variables describe the events, and each holds a variable name rather than the values themselves:
EventLabelsVariable, the variable naming each event.
EventLengthsVariable, how long each event lasted.
EventEndsVariable, when each event finished.
The last two are mutually exclusive: an event says its extent one way or the other, never both. An event with neither is an instant.
Because the properties hold names, an operation that stops a name resolving affects the property. Removing the variable clears it, and so does deleting it by assigning an empty matrix; renaming the variable carries the property across to the new name, which is a deliberate departure from MATLAB, where the designation is lost and renaming back does not restore it. Moving a variable or converting its type leaves the property alone.
An event table cannot itself carry an event table. It has no
Events property, and asking for one raises.
An interval event is half-open on the right: an event beginning at 02:00 and lasting two hours covers 02:00 and 03:00 but not 04:00. An event of zero length therefore covers nothing at all.
Three things read an event table once it is attached to a timetable by
that timetable’s Events property. syncevents copies the
events’ data onto the rows they cover, repeating a row that more than
one event covers. eventfilter selects the rows the events
matching a condition cover, and a row covered more than once is selected
once. timerange takes two event filters as bounds, running from
one event to another. In the other direction, extractevents
builds an event table out of a timetable’s own rows.
A binary operation over two timetables carrying event tables merges them, and refuses where their three event properties disagree; a row-preserving one carries the event table through unchanged.
Labels given as text are held as a cell array of character vectors,
which is how this package holds a list of names; a string given
as such is kept as one. An eventfilter compares either as text,
so a condition reads the same whichever they are.
See also: timetable, table, istimetable, eventfilter, timetable.extractevents, timetable.syncevents
Source Code: eventtable
The eventtable class contains the following properties:
Variable naming each event, given as the name of one of the event
table’s own variables, or empty when no variable names the events.
Assigning a name points the property at that variable; assigning
[] clears it. An event table built from a vector of times
alone labels its events "Event 1", "Event 2" and so
on and points this property at them, while one built from a timetable
leaves it empty, because nothing says which of that timetable’s
variables holds labels.
Variable holding how long each event lasted, given as the name of one
of the event table’s own variables, or empty when the events are
instants. The variable holds a duration or a
calendarDuration. It cannot be set while
EventEndsVariable is set; an event states its extent as a
length or as an end, not as both.
Variable holding when each event finished, given as the name of one of
the event table’s own variables, or empty when the events are
instants. The variable holds the same type as the row times. It
cannot be set while EventLengthsVariable is set; an event
states its extent as a length or as an end, not as both.
Row times, specified as a datetime or duration vector
with one element for each row of the timetable. They are stored as a
column vector whatever shape they are given in. Unlike the row names
of a table they need not be unique, sorted or present: duplicate
times, a descending order and missing times are all accepted, and each
of them merely makes the timetable irregular. You can access them
with tt.Properties.RowTimes and assign them the same
way, which recomputes TimeStep.
Time of the first row, of the same type as RowTimes. It
follows the first row: deleting the first row leaves StartTime
naming the row that is now first. A timetable left with no rows keeps
the value it had. Assigning it shifts every row time by the same
amount and preserves TimeStep.
Sampling rate, specified as a positive numeric scalar, being the
reciprocal of TimeStep measured in seconds. It is
NaN whenever the time step is a calendarDuration,
a calendar step having no fixed length in seconds, and whenever the
timetable is irregular. Assigning it regenerates the row times from
StartTime, as assigning TimeStep does.
Spacing between consecutive row times, specified as a duration
or calendarDuration scalar, or a NaN duration when the
timetable is irregular. Two rows or more always imply a step of their
own and it is read off them afresh, so a subset with a gap in it steps
by nothing and a reversed one steps backwards. Fewer than two rows
imply nothing, and there it matters how the step was arrived at: one
given by 'TimeStep' or 'SampleRate' is remembered,
while one read off the row times is not and becomes NaN, its
class resetting to duration with it. A freshly built one-row
timetable has no step either way. A negative step is as regular as a
positive one. Assigning it regenerates the row times from
StartTime, even when the timetable was irregular.
Table description specified as a character vector or a string scalar.
If specified as a string scalar, it is converted and stored internally
as a character vector. You can access the Description property
of a table tbl with tbl.Properties.Description.
Additional table information, specified as an array. Any type of data
can be attached using this property. You can access the UserData
property of a table tbl with tbl.Properties.UserData.
Dimension names specified as a two-element cell array of character
vectors or a two-element string array. If specified as a string array,
it is converted and stored internally as a cell array of character
vectors. You can access the DimensionNames property of a table
tbl with tbl.Properties.DimensionNames.
By default, DimensionNames is specified as
'Row', 'Variables'. You can access table data per rows or per
columns by using either one of the two dimension names, respectively.
However, if the table contains row names, then the first element of the
DimensionNames corresponds to the row names.
Variable names, specified as a cell array of character vectors or a
string array. If specified as a string array, it is converted and stored
internally as a cell array of character vectors. All elements must be
nonempty and distinct, and their number must equal the number of
variables. You can access the data type of a specific variable by using
dot name assignment, as in tbl.varname, where
varname is the name of the variable in table tbl. If the
variable name does not exist, a new one is created.
The class of the data of each variable, defined as a cell array of
character vectors or a string array with the same number of elements as
the number of variables in the table. If specified as a string array,
it is converted and stored internally as a cell array of character
vectors. You can access the VariableTypes property of a table
tbl with tbl.Properties.VariableTypes. You can
further index specific variables to access their data type. Modifying
the elements of the VariableTypes property automatically converts
the underlying data of the corresponding variable into the specified
data types provided that a valid conversion is requested.
Variable descriptions, specified as a cell array of character vectors or
a string array. If specified as a string array, it is converted and
stored internally as a cell array of character vectors. If not empty
(default), it must contain the same number of elements as the number of
variables. If a specific variable does not have a description, this can
be specified with an individual empty character vector or an empty
string. You can access the VariableDescriptions property of a
table tbl with tbl.Properties.VariableDescriptions.
You can further index specific variables to access their description.
Assigning an empty cell or string array returns the property to its
default, and describing a single variable of a table that has no
descriptions gives the remaining variables an empty description.
Variable units, specified as a cell array of character vectors or a
string array. If specified as a string array, it is converted and stored
internally as a cell array of character vectors. If not empty (default),
it must contain the same number of elements as the number of variables.
If a specific variable does not have a unit, this can be specified with
an individual empty character vector or an empty string. You can access
the VariableUnits property of a table tbl with
tbl.Properties.VariableUnits. You can further index
specific variables to access their unit. Assigning an empty cell or
string array returns the property to its default, and giving a unit to
a single variable of a table that has none gives the remaining
variables an empty unit.
Continuity of each variable, specified as a cell array of character
vectors or a string array carrying one element per variable, each of
them 'unset', 'continuous', 'step' or
'event'. It is empty by default, and assigning {} or
[] clears it. If specified as a string array, it is converted
and stored internally as a cell array of character vectors. You can
access it with tbl.Properties.VariableContinuity and you
can index individual variables to read or assign their continuity.
A table carries the property but does not act on it, which is
also how MATLAB behaves. A timetable uses it to choose the
default fill method of each variable when resampling.
MATLAB stores this property as a matlab.tabular.Continuity
enumeration. Octave has no enumeration classes, so it is stored and
returned here as a cell array of character vectors, as
VariableNames and VariableUnits are.
Custom properties that contain metadata of a table and its variables.
By default, this is an empty container. Each custom property holds
either table metadata or per-variable metadata, according to the property
type ('table' or 'variable') specified when the property
is created with the addprop method. A variable-scoped property
holds one element per variable.
You can add an individual custom property only by using the
addprop method and you can only remove a custom property with the
rmprop method. To access existing custom properties use dot name
structure assignment as in
tbl.Properties.CustomProperties.PropertyName, where
PropertyName is the name used with the addprop method.
The whole set may also be taken from another table by assigning that
table’s CustomProperties to this one, which replaces every
custom property with those of the other table, their types included. A
variable-scoped property arriving that way must hold one element for
each variable of the receiving table, or be a 0-by-0 empty. Nothing
else can be assigned there.
The eventtable class offers the following public methods:
eventtable: et = eventtable ()
eventtable: et = eventtable (eventTimes)
eventtable: et = eventtable (tt)
eventtable: et = eventtable (…, Name, Value)
et = eventtable () returns an empty event table with no
events and no variables.
et = eventtable (eventTimes) returns an event table
whose events happen at eventTimes, a datetime or
duration vector. With no labels given, the events are labelled
"Event 1", "Event 2" and so on in a variable named
EventLabels, and EventLabelsVariable names it.
et = eventtable (tt) converts the timetable
tt, whose row times become the event times and whose variables
are kept as they are. No variable is guessed to be the labels, so
EventLabelsVariable is left empty unless
'EventLabelsVariable' says which one it is.
The following Name-Value options are supported:
| Name | Value |
|---|---|
'EventLabels' | A scalar or a vector with one element
per event, naming the events. It may be of any type other than
datetime, duration, calendarDuration,
table and timetable. A scalar labels every event alike.
It is added as a variable named EventLabels. |
'EventLengths' | A duration or
calendarDuration, scalar or one element per event, saying how
long each event lasted. Only a duration is accepted when the
event times are durations. It is added as a variable named
EventLengths. |
'EventEnds' | A scalar or one element per event, of
the same type as the event times, saying when each event finished. It
is added as a variable named EventEnds. |
'EventLabelsVariable' | The name of a variable of tt that names the events. Only with a timetable input. |
'EventLengthsVariable' | The name of a variable of tt that holds the event lengths. Only with a timetable input. |
'EventEndsVariable' | The name of a variable of tt that holds the event end times. Only with a timetable input. |
A length and an end are mutually exclusive, however they are given,
and so are 'EventLabels' and 'EventLabelsVariable'.
See also: timetable, table.table2timetable
An event table is a timetable whose rows are events. Given only the times, it labels them Event 1, Event 2 and so on and points EventLabelsVariable at the variable holding them.
t0 = datetime (2024, 3, 1); eventtable (t0 + hours ([2; 9; 14]))
ans =
3x1 eventtable
Time EventLabels
____________________ ___________
01-Mar-2024 02:00:00 {'Event 1'}
01-Mar-2024 09:00:00 {'Event 2'}
01-Mar-2024 14:00:00 {'Event 3'}
EventLabels names the events, and EventLengths makes each of them an interval rather than an instant. An interval runs from the event's own time and stops short of its end, so a two-hour event beginning at 02:00 covers 02:00 and 03:00 but not 04:00.
t0 = datetime (2024, 3, 1);
ET = eventtable (t0 + hours ([2; 9]), ...
'EventLabels', ["rain"; "snow"], ...
'EventLengths', hours ([2; 1]))
ET =
2x2 eventtable
Time EventLabels EventLengths
____________________ ___________ ____________
01-Mar-2024 02:00:00 {'rain' } 2 hr
01-Mar-2024 09:00:00 {'snow' } 1 hr
The three properties hold variable names, not the values.
ET.Properties.EventLabelsVariable
ans = EventLabels
EventEnds says the same thing the other way round. A length and an end are mutually exclusive: an event states its extent once.
t0 = datetime (2024, 3, 1);
eventtable (t0 + hours ([2; 9]), 'EventLabels', ["rain"; "snow"], ...
'EventEnds', t0 + hours ([4; 10]))
ans =
2x2 eventtable
Time EventLabels EventEnds
____________________ ___________ ____________________
01-Mar-2024 02:00:00 {'rain' } 01-Mar-2024 04:00:00
01-Mar-2024 09:00:00 {'snow' } 01-Mar-2024 10:00:00
An existing timetable becomes an event table, keeping its variables. No variable is guessed to hold the labels, so EventLabelsVariable has to be named if one of them does.
t0 = datetime (2024, 3, 1); Phase = ["dry"; "wet"]; Depth = [12; 45]; TT = timetable (Phase, Depth, 'RowTimes', t0 + hours ([2; 9])); ET = eventtable (TT, 'EventLabelsVariable', 'Phase'); ET.Properties.EventLabelsVariable
ans = Phase
The event table is attached to the timetable it describes, and a row-preserving operation carries it through untouched.
t0 = datetime (2024, 3, 1);
TT = timetable ([12; 45; 23; 31], 'RowTimes', t0 + hours (0:3)', ...
'VariableNames', {'Depth'});
TT.Properties.Events = eventtable (t0 + hours ([1; 3]), ...
'EventLabels', ["rain"; "snow"]);
height (sortrows (TT).Properties.Events)
ans = 2
eventtable: et = eventtable.empty ()
eventtable: et = eventtable.empty (r, v)
eventtable: et = eventtable.empty (sz)
The arguments are those of timetable.empty, which this is in
every respect but the class of what comes back: a 0-by-0 event table
with no arguments, and otherwise one of r rows and v
variables, at least one of the two being zero. None of the three
event properties is set, there being no variable for one to name.
See also: eventtable, timetable