Class: TermStructure

CIQ. TermStructure


new TermStructure(params)

Creates a term structure chart.

Yield Curve Figure. Term structure chart with comparison and historical curves, crosshairs, and heads up display.

A term structure compares the value of related financial instruments. For example, the U.S. Treasury yield curve is a term structure that compares the interest rates of Treasury securities that have different maturity dates (see image above).

A term structure chart shows the different instruments on the x‑axis — with either uniform or scaled spacing — and the instrument values on the y‑axis. A chart consists of a main curve for a primary entity (such as the U.S. Treasury) and optional comparison curves for other entities or historical curves for the primary entity. (Entities create or provide instruments or serve as a means of relating instruments.)

The chart supports daily data for historical points and intra-day data for the current date. The chart expects data to be in masterData. If the useQuotefeed parameter is specified, the chart leverages the quote feed to update masterData with the required date range. 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 date is a weekday. Otherwise, the chart displays an error to the user. If using a quote feed, the chart sets the refresh interval to five seconds.

Term structure charts support "live" dates and, for historical curves, relative dates (see setCurveDate).

Term structure charts can be linked to time series charts for in-depth data analysis (see CIQ.UI.CurveEdit).

For more information on term structures, see the Term Structures Introduction tutorial.

Parameters:
Name Type Description
params object

Configuration parameters.

Properties
Name Type Argument Default Description
stx CIQ.ChartEngine

A reference to the chart engine.

spacingType string <optional>
"scaled"

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

dataField string <optional>
"yield"

Initial data field.

fieldsToFormatAsPercent Array.<string> <optional>
["yield"]

Fields for which values are formatted as percents.

drawShading boolean <optional>
true

Specifies whether to draw the chart background shading which visually groups instruments.

useQuotefeed boolean <optional>
true

Specifies whether the term structure should use the quote feed to attempt to find any quotes not present in masterData.

showcaseFreshPoints boolean <optional>
true

Specifies whether fresh data point updates should be highlighted to call attention to the update. Data point updates are fresh if they occur within the current time minus params.pointFreshnessTimeout.

pointFreshnessTimeout number <optional>
10

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

showUpdateAnimations boolean <optional>
true

Specifies whether to animate changes to data point values.

showUpdateStamp boolean <optional>
true

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

showUpdateStampSeconds boolean <optional>
true

Specifies whether the update time stamp should display seconds (see params.showUpdateStamp).

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.

Classes

HUD

Methods


<static> calculateRelativeDate(params)

Calculates a date relative to a reference date. For example, calculates the date that is 10 days prior to the current date.

Parameters:
Name Type Description
params object

Function parameters.

Properties
Name Type Description
reference Date

The date from which the relative date is calculated.

timeUnit string

The unit of time by which the relative date is offset from the reference date. Must be "day", "week", "month", or "year".

multiplier number

The number of time units the relative date is offset from the reference date. A negative number offsets the date into the past; for example, -10 specifies a date 10 time units (days, weeks, months, or years) in the past. A positive number offsets the date into the future; for example, 2 specifies a date two days, weeks, months, or years in the future. Zero makes the relative date the same as the reference date regardless of time unit.

Since:
  • 8.2.0

Returns:

The calculated relative date.

Type
Date

<static> sortInstruments(instruments)

Sorts term structure instruments by their names.

Instrument names take the form "n Category", where "n" is a number and "Category" is one of DY, WK, MO, YR, ST, MT, and LT (day, week, month, year, short term, medium term, and long term, respectively); for example, 30 DY, 3 MO, 10 YR.

Categories sort in the order shown above; DY is lower in the sort order than WK, which is lower than MO, and so forth. Within categories, instruments are sorted by the numerical portion of the instrument name.

The current sorting implementation supports yield curves and other common financial instruments. However, term structures can include a wide variety of instruments and instrument naming conventions.

Depending on the instruments you are working with, you may wish to replace this function with your own custom sorting function. Expect the function to be called with an unsorted list of all instruments (no duplicates) from all active curves. Return an array sorted however you desire.

Parameters:
Name Type Description
instruments Array

The instruments to be rendered.

Since:
  • 8.0.0

Returns:

The instruments in sorted order.

Type
Array

addCurve(symbol, date, params [, cb])

Adds a secondary curve to the term structure chart.

Parameters:
Name Type Argument Description
symbol string

Market symbol that identifies the instrument depicted by the secondary curve.

date Date | string | object

Date for the secondary curve. Can be a Date object, a string acceptable by the Date.parse() method, an object that represents a relative date (for example, { timeUnit: "day", multiplier: -1 }, see timeUnit and multiplier below), or the value "live", which specifies the current date.

When a term structure is "live", the chart can be reloaded at a later date and the term structure will be reconstructed for that date (the current date) regardless of when the term structure was created.

Relative dates apply to historical curves, which are primary entity curves created for dates in the past.

Properties
Name Type Argument Description
timeUnit string <optional>

Unit of time by which a relative date is offset from the date of the main curve. See calculateRelativeDate for valid values.

multiplier number <optional>

Number of time units a relative date is offset from the date of the main curve. A negative number offsets the date into the past; a positive number, the future. Zero locks the date of the secondary curve to the date of the main curve.

params object

Specifications for the secondary curve.

Properties
Name Type Argument Description
color string <optional>

Color of the secondary curve. Must be an RGB, RBGA, or six‑digit hexadecimal color number; for example, "rgb(255, 255, 255)", "rgba(255, 255, 255, 0.5)", or "#FFFFFF".

Note: Three‑digit hexadecimal color numbers and CSS color keywords, such as "white", are not valid.

noRecord boolean <optional>

When true, prevents recording of the secondary curve data to the chart layout, CIQ.ChartEngine#layout. This parameter is set to true when importing curves (for example, when reloading a chart that has secondary curves), which prevents the state of the curve midway through loading from becoming the new source of layout data.

cb function <optional>

Function called when the curve has been added to the chart and the data for the curve is available.

Since:
  • 7.5.0
  • 8.2.0 Added date.timeUnit and date.multiplier parameters to enable relative dates. Added support for the value "live" when date is a string to enable specification of the current date.

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:

An object containing the instrument spacing and curve width.

Type
Object

calculateScaledSpacingUnits(instruments)

Calculates scaled spacing units. Because scaling the x-axis linearly with respect to time can (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 an 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


deselectCurvePoints( [curveId])

Deselects all data points that have been selected on a curve. Typically, data points are selected to show curve spreads (see CIQ.ChartEngine#drawTermStructureSpreads).

Called whenever a curve is removed or substantively modified; for example, when a new date is selected for the curve.

Defaults to the main curve.

Parameters:
Name Type Argument Default Description
curveId String <optional>
"_main_curve"

Identifies the curve for which points are delected. If not specified, points are deselected on the main curve.

Since:
  • 7.5.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 CIQ.ChartEngine

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 canvasStyleengine method to find a CSS class with the namestx_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

modifyCurve(curveId [, params])

Modifies a curve on the term structure chart.

Parameters:
Name Type Argument Description
curveId string

Identifies the curve to be modified.

params object <optional>

Parameters that specify curve modifications. If this parameter is undefined, the function returns without doing anything.

Properties
Name Type Argument Description
color string <optional>

A new color to apply to the curve. Must be an RGB, RBGA, or six‑digit hexadecimal color number; for example, "rgb(255, 255, 255)", "rgba(255, 255, 255, 0.5)", or "#FFFFFF".

Note: Three‑digit hexadecimal color numbers and CSS color keywords, such as "white", are not valid.

noRecord boolean <optional>

When true, prevents recording of the curve modifications to the chart layout, CIQ.ChartEngine#layout.

Since:
  • 7.5.0
  • 8.2.0 Added params.noRecord.

recalculateRelativeDates( [params])

Recalculates any relative dates if necessary; for example, when the main curve date has changed.

Parameters:
Name Type Argument Description
params object <optional>

Function parameters.

Properties
Name Type Argument Description
noDraw boolean <optional>

When true, prevents the chart from being redrawn when the the dates are recalculated.

Since:
  • 8.2.0


removeCurve( [curveId])

Removes a secondary curve from the term structure chart.

Parameters:
Name Type Argument Description
curveId String <optional>

Identifies the curve to be removed. If the parameter is undefined or identifies the main curve, this function returns without doing anything.

Since:
  • 7.5.0


setCurveDate(date [, curve] [, params])

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, the function 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 Default Description
date Date | string | object

The date for which the term structure curve is created. Can be a Date object, a string acceptable by the Date.parse() method, an object that represents a relative date (for example, { timeUnit: "day", multiplier: -1 }, see timeUnit and multiplier below), or the value "live", which specifies the current date.

When a term structure is "live", the chart can be reloaded at a later date and the term structure will be reconstructed for that date (the current date) regardless of when the term structure was created.

Relative dates apply to historical curves, which are primary entity curves created for dates in the past.

Properties
Name Type Argument Description
timeUnit string <optional>

Unit of time by which a relative date is offset from the date of the main curve. See calculateRelativeDate for valid values.

multiplier number <optional>

Number of time units a relative date is offset from the date of the main curve. A negative number offsets the date into the past; a positive number, the future. Zero locks the date of the secondary curve to the date of the main curve.

curve string <optional>

Identifies the curve to which date applies. If this parameter is not provided, defaults to the main term structure curve.

params object <optional>
{}

Curve specifications.

Properties
Name Type Argument Description
noRecord boolean <optional>

When true, prevents recording of the curve data to the chart layout, CIQ.ChartEngine#layout. This parameter is set to true when importing curves (for example, when reloading the chart), which prevents the state of the curve midway through loading from becoming the new source of layout data.

noDraw boolean <optional>

When true, prevents the chart from being redrawn when the curve date is set.

Since:
  • 7.3.0
  • 7.5.0 Added params and params.noRecord parameters.
  • 8.2.0 Added params.noDraw parameter. Added date.timeUnit and date.multiplier parameters to enable relative dates. Added support for the value "live" when date is a string to enable specification of the current date.
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 Boolean

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 Boolean

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 Boolean

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

Spacing type, should be either "scaled" or "uniform". If this parameter is undefined, the function returns without doing anything.

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 data point values.

Parameters:
Name Type Description
value Boolean

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