Term Structures

Introduction

Term structures describe the relationship of financial instruments that have an intrinsic value in common, such as price or yield. Typical term structures include:

  • Yield Curve — Compares bond and other fixed-income instrument yields at specified maturity dates. The U.S. Treasury yield curve is a well known example.

  • Options Implied Volatility Curve — Graphs volatility vs. strike price of option contracts that have the same underlying security and expiration date.

  • Commodity and Financial Instrument Futures — Compares futures contract prices at various delivery dates.

Term structure charts can be created for any collection of instruments based on criteria that you specify.

In this tutorial

You will learn how to create a basic term structure chart connected to a static data source. You will also learn the data format required by term structure charts.

Before you begin

This tutorial requires version 7.4.0 or later of the ChartIQ library.

To obtain a copy of the library, see Getting the Library.

Creating a chart

A basic term structure chart can be created with simple markup and a few lines of JavaScript.

Create an HTML file named termstructure.html at the root of your ChartIQ library on your web server. Add the following markup and JavaScript to the file:

<!doctype html>
<html>
<head>
<meta name="viewport" content="user-scalable=no, width=device-width, initial-scale=1, maximum-scale=1">

<!-- Include the main ChartIQ CSS file. -->
<link rel="stylesheet" type="text/css" href="css/stx-chart.css" media="screen" />

<!-- Reference the main ChartIQ JavaScript library file. -->
<script src="js/chartiq.js"></script>

<!-- Reference the term structure plug-in. -->
<script src="plugins/termstructure/termstructure.js"></script>

<script>
// Create a handler that displays the term structure chart.
function displayChart() {
    // Create a chart engine instance.
    var stxx = new CIQ.ChartEngine({container: document.querySelector(".chartContainer")});

    // Create a term structure object and associate it with the chart engine.
    new CIQ.TermStructure({stx: stxx, useQuotefeed: false});

    // Notify the chart engine of the chart type.
    stxx.setChartType("termstructure");

    // Load the chart.
    stxx.loadChart("US-T BENCHMARK", {
        masterData: quotes // Add a data source to the chart.
    });
};
</script>
</head>

<!-- Set the onload handler. -->
<body onload="displayChart()">

<!-- Create the container for the chart. -->
<div class="chartContainer" style="width: 1200px; height: 675px; position: relative;"></div>

</body>

<!-- Create a static data source for the term structure. -->
<script>
var quotes = [
    {
        DT: new Date(),
        Date: new Date().toISOString(),
        termStructure: {
             "1 MO": {yield: 2.31},
             "2 MO": {yield: 2.37},
             "3 MO": {yield: 2.41},
             "6 MO": {yield: 2.53},
             "1 YR": {yield: 2.70},
             "2 YR": {yield: 2.83},
             "3 YR": {yield: 2.86},
             "5 YR": {yield: 2.89},
             "7 YR": {yield: 2.98},
            "10 YR": {yield: 3.06},
            "20 YR": {yield: 3.22},
            "30 YR": {yield: 3.32}
        }
    }
];
</script>
</html>

Source Code Overview

Let's examine the key elements of our file from top to bottom.

stx-chart.css

<link rel="stylesheet" type="text/css" href="css/stx-chart.css" media="screen" />

The main style sheet for term structure charts (and any ChartIQ chart) is stx-chart.css. The style sheet contains styles for the various elements of the chart, such as backgrounds, titles, controls, and fields. You should always include stx-chart.css in your chart applications.

Note: Do not edit stx-chart.css (or any ChartIQ library CSS file). To change a style that is in stx-chart.css, override the style later in the CSS cascade by subsequently loading a CSS file that contains a revised version of the style or by adding CSS styling directly to HTML elements.

chartiq.js

<script src="js/chartiq.js"></script>

The core ChartIQ library JavaScript file is chartiq.js; it contains key functions needed to implement a basic chart. You must always include chartiq.js in your term structure chart applications.

Note: Do not edit chartiq.js or any ChartIQ library JavaScript file.

termstructure.js

<script src="plugins/termstructure/termstructure.js"></script>

Term structure charts require charting functionality beyond that provided by chartiq.js. The termstructure.js plug-in supplies the additional functionality that makes term structure charts possible.

displayChart()

<script>
function displayChart() {
    // Create a chart engine instance.
    var stxx = new CIQ.ChartEngine({container: document.querySelector(".chartContainer")});

    // Create a term structure object and associate it with the chart engine.
    new CIQ.TermStructure({stx: stxx, useQuotefeed: false});

    // Notify the chart engine of the chart type.
    stxx.setChartType("termstructure");

    // Load the chart.
    stxx.loadChart("US-T BENCHMARK", {
        masterData: quotes // Add a data source to the chart.
    });
};
</script>

The displayChart function instantiates all the objects and makes all the function calls needed to create the term structure chart.

Let's look at the function line by line.

CIQ.ChartEngine
var stxx = new CIQ.ChartEngine({container: document.querySelector(".chartContainer")});

The ChartIQ chart engine creates a chart in an HTML container element on a web page. (See the CIQ.ChartEngine API documentation.)

CIQ is the ChartIQ library namespace; it ensures that the names of ChartIQ classes, functions, variables, and so forth are unique when the ChartIQ library is used in conjunction with other JavaScript libraries. (See the CIQ namespace documentation.)

The ChartEngine constructor function takes an object as an argument. The object must include (at a minimum) a property named container. The value of container must be a reference to the HTML element used to contain the chart. In termstructure.html, the reference is to the div element identified by the class="chartContainer" CSS selector (see Chart container <div> below).

The variable stxx holds a reference to the new chart engine instance.

CIQ.TermStructure
new CIQ.TermStructure({stx: stxx, useQuotefeed: false});

The TermStructure constructor function creates the main object of the term structure plug-in. The object contains the specialized functionality that enables the chart engine to create a term structure chart. (See the CIQ.TermStructure API documentation.)

The constructor takes an object as its sole argument. The object must contain a property named stx. The value of stx must be a reference to the chart engine (stxx in our file). A variety of optional parameters may also be included. In this tutorial, we use a static data source rather than a quote feed (see Data feeds below) to provide data for the term structure; and so, we include the optional useQuotefeed parameter and set it to false.

setChartType
stxx.setChartType("termstructure");

ChartIQ supports a large number of chart types: candle charts, mountain charts, line charts. The call to setChartType is needed to identify the chart as a term structure.

loadChart()
stxx.loadChart("US-T BENCHMARK", {
    masterData: quotes
});

The loadChart function of CIQ.ChartEngine loads and renders the chart.

The first parameter provides the name of the entity that has issued or otherwise created the instruments that make up the term structure. For example, the United States Treasury issues a set of treasury bills, notes, and bonds that together form a term structure of instrument yields known as the U.S. Treasury yield curve. The Treasury yield curve is a benchmark for U.S. interest rates. Our term structure simulates the Treasury yield curve, so we're using the name “US-T BENCHMARK”.

The second parameter contains a variety of optional settings that configure the chart.

masterData

The data source of the chart is specified by the masterData property. We've set masterData to a static data source named quotes. The quotes variable references the array defined in the script tag at the bottom of termstructure.html (see Data source below). More typically, the data source is a real-time data feed. We'll examine data sources and data formats later in this tutorial.

onload handler

The displayChart function is set as the onload handler of the body element:

<body onload="displayChart()">

By making displayChart the onload handler, we ensure that the chart container div (see below) is available in the DOM when the chart engine is instantiated.

Chart container <div>

<div class="chartContainer" style="width: 1200px; height: 675px; position: relative;"></div>

A ChartIQ chart is contained in a web page div element. The div should have an id or class attribute that can be used to query the element. A reference to the element is provided to the ChartIQ chart engine, which creates a chart within the element (see CIQ.ChartEngine above).

The width and height can be whatever you like, but the CSS position attribute must be set to absolute or relative so that overlays (such as crosshairs or zoom controls) are positioned correctly on the chart.

Data source
<script>
var quotes = [
    {
        DT: new Date(),
        Date: new Date().toISOString(),
        termStructure: {
             "1 MO": {yield: 2.31},
             "2 MO": {yield: 2.37},
             "3 MO": {yield: 2.41},
             "6 MO": {yield: 2.53},
             "1 YR": {yield: 2.70},
             "2 YR": {yield: 2.83},
             "3 YR": {yield: 2.86},
             "5 YR": {yield: 2.89},
             "7 YR": {yield: 2.98},
            "10 YR": {yield: 3.06},
            "20 YR": {yield: 3.22},
            "30 YR": {yield: 3.32}
        }
    }
];
</script>

We've created a static data source for our term structure. The data source provides the names of the term structure instruments and the data for each instrument; that is, the x and y values plotted on the term structure chart.

We're simulating the U.S. Treasury yield curve, so the instrument names in our data source specify an assortment of Treasury fixed income instruments, and the data is the yield, or interest rate, of those instruments.

Run it!

Load termstructure.html into your web browser by using the localhost hostname (if you're using a local web server) or the hostname (or IP address) of your organization's web server. For example, enter the following in your browser's address bar:

http://localhost:5500/termstructure.html

You should see the following term structure chart:

Basic term structure

Understanding the chart data

Term structure charts can be created from static data or real-time data feeds. In either case, the data format is the same.

Data format

The data source for a term structure chart is ultimately an array of objects. Each object specifies information for the term structure instruments at a moment in time.

The objects contain the following fields:

  • DT — The date and time of the data as a JavaScript Date object.
  • Date — The date and time of the data in ISO 8601 format.
  • termStructure — An object that contains the data for the instruments in the term structure. Each instrument is represented by a key/value pair in the termStructure object. The key is the instrument name. The value is an object containing the instrument data.

Note: The term structure plug-in attempts to sort the instruments by the property keys (instrument names); however, we recommend that you put the keys in the order in which the instruments appear on the chart.

For example, data for the U.S. Treasury benchmark yield curve:

var quotes = [
    {
        DT: new Date(),
        Date: new Date().toISOString(),
        termStructure: {
             "1 MO": {yield: 2.31},
             "2 MO": {yield: 2.37},
             "3 MO": {yield: 2.41},
             "6 MO": {yield: 2.53},
             "1 YR": {yield: 2.70},
             "2 YR": {yield: 2.83},
             "3 YR": {yield: 2.86},
             "5 YR": {yield: 2.89},
             "7 YR": {yield: 2.98},
            "10 YR": {yield: 3.06},
            "20 YR": {yield: 3.22},
            "30 YR": {yield: 3.32}
        }
    }
    // More quotes here for different dates and times.
];

Data feeds

Term structure charts support real-time data feeds by leveraging the ChartIQ quote feed architecture. Other data feed methodologies, such as streaming, can also be used.

See the Data Integration Overview tutorial to learn more.

Conclusion

This tutorial has provided an introduction to ChartIQ term structure charts. Explore our documentation web site at https://documentation.chartiq.com to access a variety of in-depth tutorials and the complete library API documentation.

Let us know at support@chartiq.com if you have any questions.

Next Steps: