Class: TermStructure

CIQ. TermStructure


new TermStructure(params)

Creates a term structure chart.

Yield Curve

The chart shows the different instruments along the x-axis, either with uniform or scaled spacing, and the values (ask, bid, yield, etc.) along the y-axis.

The chart supports daily data for historical points and intra-day for the current day. The chart expects data to be in masterData (and if the useQuotefeed parameter is specified, leverages the quote feed to accomplish this). If for any reason the requested date is not present in masterData, the chart attempts to find a nearby point (such as a weekday if the requested day is a weekday). Otherwise, it displays an error to the user. If using a quote feed, the chart sets the refresh interval to five seconds.

Parameters:
Name Type Description
params object

Configuration parameters.

Properties
Name Type Argument Default Description
stx object

A reference to the chart engine (see CIQ.ChartEngine).

spacingType string <optional>

Initial spacing type, either "scaled" or "uniform". Defaults to "scaled".

dataField string <optional>

Initial data field. Defaults to "yield".

fieldsToFormatAsPercent array <optional>

Fields where the value should be formatted as a percent. Defaults to ["yield"].

drawShading bool <optional>

Specifies whether shading should initially be set or not. Defaults to true.

useQuotefeed bool <optional>

Specifies whether this TermStructure should use the quote feed to attempt to find any quotes not present in masterData. Defaults to true.

initialDate string <optional>

Initial curve will be the current chart symbol for the current date. Specify a different starting date here.

showcaseFreshPoints bool <optional>
true

Indicates whether recent data point updates should be highlighted to call attention to the update. Recency is based on whether the data point has been updated within the time span of the freshness timeout.

pointFreshnessTimeout number <optional>
10

The amount of time in minutes after which data points go stale.

showUpdateAnimations bool <optional>
true

Indicates whether to animate changes to data point values.

showUpdateStamp bool <optional>
true

Indicates whether an update time stamp should appear when the mouse hovers over data points.

showUpdateStampSeconds bool <optional>
true

Indicates whether the update time stamp should display seconds.

maxZoom number <optional>
5

The maximum multiple to which the chart scales when zooming. Note: Setting this number arbitrarily high does not enable arbitrary zooming. Chart internals do not allow zooming beyond a (high) multiple based on the computed maximum candle width.

Since:

  • • 7.3.0
    • 7.4.0 Added the showcaseFreshPoints, pointFreshnessTimeout, showUpdateAnimations, showUpdateStamp, showUpdateStampSeconds, and maxZoom parameters.

Methods


<static> createDataSegment()

Term structure override injection of the default createDataSegment method. this is a CIQ.ChartEngine instance.

This function is invoked by chart internals as part of the draw loop if the term structure plug-in has been initialized. The function should rarely if ever be called directly.

Since:
  • 7.3.0


animateUpdates()

Animates chart updates.

Since:
  • 7.3.0


calculateInstrumentSpacing(chart, instruments, bufferPercent)

Calculates instrument spacing. If the TermStructure instance has a spacingType of "uniform", instruments are spaced uniformly. If spacingType is set to "scaled", the spacing is calculated from the "spacing units" returned from calling calculateScaledSpacingUnits.

Parameters:
Name Type Description
chart object

The chart engine.

instruments array

An array of instruments for which the spacing units are calculated.

bufferPercent number

The percentage by which the available display width for spacing instruments is reduced on both sides of the chart.

Since:
  • 7.3.0

Returns:
Type
object

calculateScaledSpacingUnits(instruments)

Calculates scaled spacing units. Because scaling the x-axis linearly with respect to time may, depending on the term structure, result in a tight clustering of points near the left-hand side of the chart, you may wish to "smooth" the differences. In the default version, this has been done by calculating the time between the previous and current instrument, and raising that value to a 0.5 exponent.

You may wish to replace this with your own scaling. To do so, simply overwrite this method with your own version. It will be called with an array of instruments and should return a object with each instrument as a key corresponding to a unit spacing value. The relative differences between the units will be used to determine positioning along the x-axis. The first instrument should have a unit spacing of 0.

Parameters:
Name Type Description
instruments array

An array of instruments for which the scaled spacing is calculated.

Since:
  • 7.3.0

Returns:

An object containing the spacing units for the instruments.

Type
object

cancelUpdateAnimations()

Removes all active update animations. Call this function to programmatically stop the animations associated with data point updates. See CIQ.TermStructure#setUpdateAnimations.

Since:
  • 7.4.0


findHighlights(stx, isTap, clearOnly)

Determines whether the user has either tapped or moused over a data point and, if so, includes in the return object the time stamp of the last update of the data point. Called by CIQ.ChartEngine#findHighlights.

Parameters:
Name Type Description
stx object

The chart engine instance.

isTap boolean

If true, indicates that the user tapped the screen on a touch device, and thus a wider radius is used to determine which objects have been highlighted.

clearOnly boolean

Clears highlights when set to true.

Since:
  • 7.4.0

Returns:

Object that specifies boolean values for somethingChanged, anyHighlighted, and stickyArgs properties.

Type
object

formatTimeStamp(date)

Formats a date and time for the time stamp that appears when the user's mouse hovers over a data point on the chart. The time stamp shows the date and time when the data point was most recently updated.

Default formatting is "Updated YYYY-MM-dd HH:mm". Override this function to specify your own date/time formatting.

Parameters:
Name Type Description
date

A Date object or a value that can be accepted by the Date contructor function.

Since:
  • 7.4.0

Example
var dt = new Date(date);
return "Last update at: " + (dt.getMonth() + 1) + "/" + dt.getDate() + "/" + dt.getFullYear();

getInstrumentShadingColor(instrument)

Returns the shading color for an instrument. Called once for each instrument (or instrument shorthand) stored in termStructure.instruments (e.g., "1 MO", "2 MO", etc. for treasury bills). By default, this method uses the canvasStyle engine method to find a CSS class with the name stx_shading_ concatenated with the instrument or instrument shorthand with spaces removed (e.g., stx_shading_1MO). As a result, shading styles can be defined in your stylesheets.

Feel free to override this method with your own color method. The shading renderer calls getInstrumentShadingColor for each instrument and expects an RBGA color to be returned.

Parameters:
Name Type Description
instrument string

The instrument identifier.

Since:
  • 7.3.0

Returns:

A color code.

Type
string

setCurveDate(date [, curve])

Sets the date for which a term structure curve is drawn. If the value specified in date is not found in masterData and, if useQuotefeed is set in this term structure, attempts to use the quote feed to load the requested date.

For term structures that have multiple curves, the date is applied to the main curve if a value is not specified in curve.

Parameters:
Name Type Argument Description
date string

The date for which the term structure curve is drawn.

curve string <optional>

Identifies the curve to which date applies. Defaults to the main term structure curve if an argument is not provided.

Since:
  • 7.3.0

Example
var datepicker = topNode.querySelector("cq-datepicker");
if (datepicker && stx.termStructure) {
	datepicker.registerCallback(function(date) {
		stx.termStructure.setCurveDate(date);
	});
}

setDataField(field)

Sets the data field for which values are plotted on the y-axis of the term structure and then triggers a redraw of the chart. Use this function instead of setting the data field manually. See CIQ.UI.Layout#setDataField.

Parameters:
Name Type Description
field string

Defines the type of values plotted on the y-axis of the term structure graph; for example, instrument yield or volatility.

Since:
  • 7.3.0


setPointFreshnessTimeout(number)

Sets the value of the chart engine layout parameter (see CIQ.ChartEngine) that specifies the amount of time after which data points go stale.

Parameters:
Name Type Description
number number

The number of minutes for the time out.

Since:
  • 7.4.0


setShading(bool)

Sets the shading flag to the value of the bool parameter and triggers a redraw. Use this function instead of setting the value manually.

Parameters:
Name Type Description
bool bool

When true, a background color (shading) is drawn on the chart to highlight horizontal sections of the graph; when false, the background color is not drawn.

Since:
  • 7.3.0

Example
var shadingCheckbox = topNode.querySelector(".ciq-checkbox-shading");
if (shadingCheckbox) {
	shadingCheckbox.registerCallback(function(value) {
		stx.termStructure.setShading.call(stx.termStructure, value);
		shadingCheckbox.classList.toggle("ciq-active");
	});
	shadingCheckbox.currentValue = true; // Initially set check box to checked.
}

setShowcaseFreshPoints(value)

Sets the value of the chart engine layout parameter (see CIQ.ChartEngine) that indicates whether or not to highlight fresh data points.

Parameters:
Name Type Description
value bool

If true, highlight fresh data points; otherwise, do not highlight fresh data points.

Since:
  • 7.4.0


setShowUpdateStamp(value)

Sets the value of the chart engine layout parameter (see CIQ.ChartEngine) that specifies whether the update time stamp should appear for data points the user has tapped or moused over.

Parameters:
Name Type Description
value bool

If true, show the time stamp; otherwise, do not show the time stamp.

Since:
  • 7.4.0


setSpacingType(type)

Sets the spacing type and triggers a redraw. Use this instead of setting the value manually.

Parameters:
Name Type Description
type string
Since:
  • 7.3.0


setUpdateAnimations(value)

Sets the value of the chart engine layout parameter (see CIQ.ChartEngine) that specifies whether to animate changes to point values.

Parameters:
Name Type Description
value bool

If true, animate changes; otherwise, do not animate changes.

Since:
  • 7.4.0


updateTitleDate()

Updates the date in the chart title with the time the most recent update was received.

Since:
  • 7.3.0


zoomSet()

Zooms the chart in and out. Overrides the default CIQ.ChartEngine#zoomSet method. Called in response to user interaction.

Since:
  • 7.4.0