Time Span Events

Creating a Data Source

Time span events are defined by data from a static or real-time data source. The data is structured as JavaScript data access objects that represent the following:

  • Swim lanes of time span events
  • Individual time span events (which are displayed in the swim lanes)
  • Sub-events (point-in-time events that occur within time span events)

In this tutorial

You will learn how to create the data access objects that constitute a data source for time span events.

Note: The format of the data is the same regardless of whether the data source is static or real-time.

Before you begin

Please familiarize yourself with the material in the Time Span Events Introduction tutorial and Implementation tutorial.

Swim lane data objects

A swim lane of time span events is specified by a JavaScript object. The object is passed to the Time Span Events plug-in, which uses the data to display the swim lane of events.

The swim lane object contains the following properties:

  • type — A string that identifies the swim lane and the type of events contained in the swim lane; for example, "CEO" (for CEO tenures), "Order" (for institutional stock orders), or "News" (for news reports). You establish the event types according to your implementation.
  • events — An array of objects that define the individual time span events that appear in the swim lane.
  • spanType — A string that categorizes the time span events contained in the swim lane. Must be one of the following: "spanEvent", "durationEvent", or "singleEvent".
  • infoPanel — Optional. A string that specifies the panel where pop-up displays of event information appear when a marker in the swim lane is selected. Must be either "panel" or "main" to have the pop-up displays appear in the time span events panel or main chart area, respectively. To prevent pop-up displays from appearing, set the value to null or a string other than "panel" or "main"; for example, "none". Overrides the value in the infoPanel parameter of CIQ.TimeSpanEventPanel for the span type.

For example:

var ceo = {
    type: "CEO",
    events: [{label: "CEO", spanLabel: "CEO 1", startDate: "01/01/2010", endDate: "12/31/2018", bgColor: "gray"},
             {label: "CEO", spanLabel: "CEO 2", startDate: "01/01/2019", endDate: "12/31/2019", bgColor: "blue"},
             {label: "CEO", spanLabel: "CEO 3", startDate: "01/01/2020", endDate: new Date(), bgColor: "red"}],
    spanType: "spanEvent",
    infoPanel: "main"
};

Note: The values for swim lane type and event label must be identical.

The swim lane is displayed by calling the CIQ.TimeSpanEventPanel#showTimeSpanEvent function with the swim lane data object argument; for example:

stxx.timeSpanEventPanel.showTimeSpanEvent(ceo);

We'll examine this function in more detail in the Hello World Example and Hello World Example for Angular tutorials.

Span types

The spanType property of the swim lane data object specifies the type of time span events that appear in the swim lane. Time span event types include:

  • spanEvent — Span events graphically underscore a period of time on the chart. A span event marker enables easy identification of market activity during the time span of the event. Examples of span events include weather events (such as hurricanes), periods of social turmoil, and recessions.
  • durationEvent — Duration events denote a period of time on the chart, but also include sub-events that occur at points in time during the overall time span event. For example, institutional orders are typically made up of multiple trade executions that happen one after another over perhaps hours or days. The institutional order is the time span event; the trades are the point-in-time sub-events, which are denoted by markers on the chart within the span of time indicated by the time span event marker. Sub-event markers appear when the user's mouse hovers over the event or when the event is selected.
  • singleEvent — Single events occur at a point in time; they do not occur over a span of time. Single events are nevertheless included in the Time Span Events module to enable the presentation of a series of events in a swim lane of the Time Span Events panel; for example, daily news, quarterly reports, or periodic announcements.

Time span events in swim lanes specified by span type Figure. Time span events in swim lanes specified by span type: (from top to bottom) durationEvent, spanEvent, singleEvent.

Event data objects

The time span event markers that occupy a swim lane are defined by the data access objects contained in the events array of the swim lane data object.

The objects contain a subset of the following properties based on the type of the event, which is determined by the spanType property of the swim lane object:

Required
Recommended
Optional
Not applicable

Property Data type Description spanEvent durationEvent singleEvent
label String The kind of event. Note: Must be identical to the type property of the swim lane data object.
spanLabel String The label that appears on the marker (spanEvent only). Also appears as the heading in the event marker pop-up display if the headline property (see below) is not specified.
startDate Date object or string acceptable by new Date(). The starting date of the time span event.
endDate Date object or string acceptable by new Date(). The ending date of the time span event.
bgColor String The background color of the event marker. Must be a valid HTML color code, such as "red" or "#FF0000". The default value is "#BBBBBB", which can be modified in the constants.js file in the plugins/timespanevent folder.
textColor String The color of the text of the event marker. Must be a valid HTML color code, such as "white" or "#FFFFFF". The default value is "#FFFFFF", which can be modified in the constants.js file in the plugins/timespanevent folder.
subChildren Array An array of data access objects that define the sub-events of the time span event. See Sub-event data objects below.
markerShape String Specifies the shape of the sub-event markers. Sub-events include the subChildren of duration events, the starting time of span and duration events, and the time of occurrence of single events. (The starting time and time of occurrence markers appear when span, duration, or single event markers are selected.) Must be one of "circle", "square", or "callout".
headline String The heading that appears in the pop-up display of the sub-event marker that represents the start of the time span event.
story String The body text that appears in the pop-up display of the sub-event marker that represents the start of the time span event.
category String A CSS class name that is added to the HTML DOM nodes that represent the sub-event markers of the time span event. Sub-events include the subChildren of duration events, the starting time of span and duration events, and the time of occurrence of single events. (The starting time and time of occurrence markers appear when span, duration, or single event markers are selected.) The class name becomes part of a CSS class selector that includes the "stx-marker" and "stx-visual" classes. For example, if the category is "publication", the selector is stx-marker.publication stx-visual (see Customization below). A variety of marker style rule-sets are contained in the examples/markers/tradeAnalyticsSample.css file (which we'll work with in the tutorials that follow).
glyph String The file name and path of a png, jpeg, or other image file. The file name and path are set as the value of the src attribute of a new Image object which provides the visual depiction of the event. Note: The file path must start from within the chartiq library folder; for example plugins/timespanevent/images/alert.png.
isActive Boolean Indicates whether the event is ongoing; that is, has not yet finished. Typically only one event in a swim lane is considered to be active. The active event is indicated by a directional icon at the most recent date and time (rightmost end) of the event time span.
showPriceLines Boolean Determines whether horizontal lines are drawn from the first and last sub-events to the y-axis, pointing out the values related to those sub-events.
alwaysZoom Boolean If set to true, the event marker zooms the display when double-clicked (or double-tapped) even if the event does not have sub-children. The zoom fills the chart area with the date range of the time span event. Overrides the property of the same name in CIQ.TimeSpanEventPanel. Note: Duration events with sub-children always zoom regardless of this setting.
eventZoomPeriodicity Object The periodicity of the event zoom date range.

Sub-event data objects

Time span events of the durationEvent span type have point-in-time sub-events. The sub-events are specified by an array of data access objects assigned to the subChildren property of the time span event.

The objects contain the following properties:

Required
Recommended

Property Data type Description
date Date object
Note: Cannot be a string
The date of the sub-event.
price Number Duration events typically involve securities orders; the sub-events are individual trade transactions. The value of the price property is usually the price at which the security was bought or sold. See also showPricelines in Event data objects above.
headline String The heading that appears in the pop-up display of the sub-event marker.
story String The body text that appears in the pop-up display of the sub-event marker.

Marker examples

The following examples show the minimum specifications for the three types of event markers. We'll look at more complete examples in the Hello World Example and Hello World Example for Angular tutorials.

spanEvent

var weatherEvents = [
    {
        label: "Weather",
        spanLabel: "Drought",
        startDate: "2019-06-01T00:00:00",
        endDate: "2019-09-01T24:00:00"
    },
    {
        label: "Weather",
        spanLabel: "Hurricane",
        startDate: "2019-10-01T00:00:00",
        endDate: "2019-10-11T24:00:00"
    }
];

durationEvent

var orderEvents = [
    {
        label: "Order",
        startDate: "2020-03-01T10:00:00",
        endDate: "2020-03-01T10:30:00",
        category: "trade",
        markerShape: "circle",
        subChildren: [
            {
                date: new Date("2020-03-01T10:15:00"),
                price: 172.01
            },
            {
                date: new Date("2020-03-01T10:30:00"),
                price: 172.10
            }
        ]
    },
    {
        label: "Order",
        startDate: "2020-03-10T13:00:00",
        endDate: "2020-03-10T13:45:00",
        category: "trade",
        markerShape: "circle",
        subChildren: [
            {
                date: new Date("2020-03-10T13:20:00"),
                price: 173.50
            },
            {
                date: new Date("2020-03-10T13:45:00"),
                price: 174.10
            }
        ]
    }
];

singleEvent

var reportEvents = [
    {
        label: "Report",
        startDate: "2020-01-01T09:30:00"
    },
    {
        label: "Report",
        startDate: "2020-02-01T09:30:00"
    },
    {
        label: "Report",
        startDate: "2020-03-01T09:30:00"
    }
];

Each of these arrays would be the value assigned to the events property of a swim lane data object (with type equal to "Weather", "Order", and "Report" and spanType equal to "spanEvent", "durationEvent", and "singleEvent" respectively).

Customization

Time span event markers can be customized with different background colors, font colors, icons, and more. The properties of the event data access object provide a variety of customization settings (see Event data objects above).

For example, to create a span event that displays green text on a blue background:

{
    label: "Weather",
    spanLabel: "Winter storm",
    startDate: "2020-01-01T05:00:00",
    endDate: "2020-01-03T13:30:00",
    textColor: "green",
    bgColor: "blue",
}

or a single event with an image file as the event marker:

{
    label: "News",
    startDate: "2020-04-01T09:30",
    headline: "Company News",
    story: "Sales are up!",
    glyph: "plugins/timespanevent/images/news.png"
}

Many of the default visual characteristics of time span event markers are set by constants in the constants.js file in the plugins/timespanevent folder. You can modify the constants to adjust event marker spacing, opacity, and so forth.

You can also modify the constants by means of the customConstants parameter of the CIQ.TimeSpanEventPanel constructor function.

CSS

CSS rule-sets can be created to style elements such as the sub-event markers. The tradeAnalyticsSample.css file in the examples/markers folder contains some sample rule-sets.

Sub-event markers are DOM elements, structured basically as follows:

<div class="stx-marker highlight">
    <div class="stx-visual">
        <div class="stx-marker-content">
            <div class="stx-marker stx-performance-marker stx-marker-expand"><h4></h4><p></p></div>
        </div>
    </div>
    <div class="stx-stem"></div>
</div>

The marker (DOM element) has a variety of default class attributes; notice "stx-marker" and "stx-visual".

The category property of a time span event is added to the class list of sub-event markers. (See Event data objects above for information on categories.)

For example, the category of the following time span event is "publication".

{
    label: "Report",
    startDate: "2020-01-01T09:30:00",
    category: "publication"
}

The DOM element that represents a sub-event marker for this time span event would look like this:

<div class="stx-marker highlight publication">
    <div class="stx-visual">
        <div class="stx-marker-content">
            <div class="stx-marker stx-performance-marker stx-marker-expand"><h4></h4><p></p></div>
        </div>
    </div>
    <div class="stx-stem"></div>
</div>

And so, we can style the sub-event marker (and any sub-event marker for this category) by creating a CSS rule-set with the selector .stx-marker.publication stx-visual:

.stx-marker.publication .stx-visual {
    background: #0f0;
    width: 10px;
    height: 10px;
}

Note: Background color in the rule-set is overridden by the color specified in the bgColor property of the event data objects (see the Event data objects section above).

Conclusion

This tutorial examined how to structure data for the Time Span Events plug-in.

Next, we'll develop a working example that displays different types of time span events.

Next Steps: