Skip to main content

Events

Overview

To organize time based data in XINA, we useemploy events, which come in two forms: instants, referring to a single moment in time, and intervals, referring to a range of time. The goal for these componentsevents is to make it easy to find, compare, and trend data. Each has their own databases and include fields for:

  • type indicate how the instant/intervalevent should be viewed and interpretted
  • UUID (universally unique identifier)identifier, generated at the creation of the event)
  • numeric primary and secondary IDs (meaning can depend on subtype)
  • plain text label (up to 128 bytes)
  • plain text or HTML content
  • optional JSON object metadata

Why all these IDs? The UUID uniquely identifies an instant / interval,event, and is the only way to permanently, globally specify it. It should be applied at the time of creation to ensure consistency even if data is reprocessed. The primary / secondary IDs are optional, and can be used as needed. The general idea is that its much faster and more reliable to query numbers than text, so this is the best way to relateindicate instantsevents andhaving intervals.commmon meaning.

Instants

Instants provide a reference to a single moment in time. They are not intended to imply any duration.

Instant Database

Default Location

<model>.data.ins

<model>.data.insf (single file per instant)

<model>.data.insfs (multi file per instant)

Required Fields

field type description
uuid uuid UUID
p_id int(8) primary ID
s_id int(8) secondary ID
t instant(us) time
type int(2) instant type code
level int(1) level code
label utf8vstring(128) plain text label
content utf8text extended text / CSV / HTML
meta jsonobject additional metadata as needed
conf jsonobject additional information specific to type

Standard Types

type code description
message 0 Basic instant, recommended to use standard IDs to indicate common events
alert 1 Higher priority variant of message
2D dataset (DSV) 100 General purpose 2D data set (see below)

Intervals

Intervals provide a reference to a span of time, specified by a start time and an end time.

Interval Database

Default Location

<model>.data.int

<model>.data.intf (single file per interval)

<model>.data.intfs (multi file per interval)

Required Fields

field type description
uuid uuid UUID
p_id int(8) primary ID
s_id int(4) secondary ID
t_start instant(us) start time (inclusive)
t_end instan(us)t end time (exclusive)
duration duration t_end - t_start
type int(2) interval type code
level int(1) level code
label utf8vstring(128) plain text label
content utf8text extended text / CSV / HTML
meta jsonobject additional metadata as needed
conf jsonobject additional information specific to type

Standard Types

type code description
marker 0 Basic interval, recommended to use standard IDs to indicate common events
test 1 TODO
2D dataset (DSV) 100 General purpose 2D data set (see below)

2D Dataset Format

The event standard type 100 indicates a 2D data set. This is typically used with the single file per event database structure, in which case the file will contain the data set. For event databases without files, the data is stored in the content field. This is only recommended for small datasets (less than 1MB).

Files must be either ASCII or UTF-8 encoded. New lines will be interpretted from either \n or \r\n. The conf object may define other customization of the format:

Conf Definition

Key Value Default Description
delimiter string auto detect (',', '\t', ';') value delimiter
quoteChar character " (double quote character) value quote character
ignoreLines number 0 number of lines to skip before the header
invalid null, 'NaN', number null preferred interpretation of invalid literal
nan null, 'NaN', number null preferred interpretation of 'Nan' literal
pInfinity null, 'Inf', number null preferred interpretation of positive 'Infinity' literal
nInfinity null, 'Inf', number null preferred interpretation of negative 'Infinity' literal
utc boolean false if true, interpret all unzoned timestamps as UTC

Starting after the number provided for ignoreLines, the content must include a header for each column, with a name and optional unit in parentheses. Special standard unit names may be used to indicate time types, which will apply different processing to the column:

Unit Description
ts text timestamp, interpretted in local browser timezone (absent explicit zone)
ts_utc text timestamp, interpretted as UTC timezone (absent explicit zone)
unix_s Unix time in seconds
unix_ms Unix time in milliseconds
unix_us Unix time in microseconds