Internal Study objects

Understanding the Study Descriptor Object

Every time a study is added to the chart a study descriptor object is created to track all its values. These default values can be inspected by your application, but should not be directly changed. Feel free to add your own custom values to the study description to track any additional pieces of information that may required by your application.

Here is a screenshot in the debugger showing the rsi entry from the layout’s studies object.

Some of the more common properties of the study descriptor include:

Property Description
type The study’s key which was passed from the addStudy call.
name The unique name of the study instance. It is created by combining the type with the inputs. Unique names are necessary in order that multiple instances of the same study store their outputs separately. The name and the inputs.id are set the same, and the name used as the key to the entry within the stxx.layout.studies object. If the type is present in the translations file, the name will be translated when using other languages.
inputs The values used to help perform the study calculations. This will include values such as period, fields, configurable parameters, etc. They will also be presented on the Study dialog to allow the user to configure the study.
outputs The values which will be displayed by the study. Each value is assigned a color or an optional object that defines a customized line.
outputMap The fields in the dataSegment which will be read to retrieve the values used to render the study. These are automatically generated for each key in outputs by adding the study name. In rare cases, such as when outputs are to be found from quotefeed data, the outputMap will need to be programmatically adjusted.
overlay A flag indicating if the study is to be superimposed upon another panel.
panel The name of the panel in which the study will appear. The panel name, if not supplied when the study is added, will be the same as the study instance name.
parameters Additional values which help perform the study rendering.
study A reference to the study definition which was used to create this study instance. Usually, this is from CIQ.Studies.studyLibrary, but it can be supplied by the programmer as well. Once added to the study descriptor, it should not be modified (in legacy implementations, this was called libraryEntry, which is still included in the descriptor for backwards compatibility).
startFrom An index into the scrubbed array from where calculations for the study need to made. Any records prior to the one indexed will already contain calculated values.
underlay A flag indicating the study is to be subimposed on another panel.

Typical values within the study definition, which is used to create the descriptor, are discussed below.

Understanding the Study Definition

If a study descriptor represents an instance of a study, then a study definition would be its prototype. The study definition is an object which contains the default settings for a study, which will then be used to create the descriptor at the time the study is added to the chart.

Here is a typical study definition. It is for the “RAVI” study type, and it is a built-in study found within the CIQ.Studies.studyLibrary:

"RAVI": {
    "name": "RAVI",
    "seriesFN": CIQ.Studies.displayRAVI,
    "calculateFN": CIQ.Studies.calculatePriceOscillator,
    "inputs": {"Field":"field", "Moving Average Type":"vdma", "Short Cycle":7, "Long Cycle":65},"outputs": {"Increasing Bar":"#00DD00", "Decreasing Bar":"#FF0000"},
    "parameters": {
        template:"studyOverZones",
        init:{studyOverZonesEnabled:true, studyOverBoughtValue:3, studyOverBoughtColor:"auto", studyOverSoldValue:-3, studyOverSoldColor:"auto"}
    }
}

Below are some of the more common properties of the study definition.

name – Full name of the study. Optional, this name can be used when referencing a study in a menu or in a dialog, for ease of understanding. Our web-components use this value on the drop down menu.

inputs – Default arguments passed into the study.

Inputs are used by the study to help compute its result.

The “inputs” field is not required, but if it is omitted, a default input of {"Period":14} will be created. This default exists since most studies utilize a period, and 14 is a typical setting. To force the study to have no inputs, set inputs to {}. An input can have any name as long as it is unique to the list of inputs, and does not use a reserved name (id, display).

Sidebar: Reserved input fields and Study Names

inputs.display - This reserved field is used to store a display-friendly name for the study instance. If not present, it is originally generated to be the same as inputs.id. It can also be modified at any time after the study is created. Note that it will not be translated to other languages when using CIQ.I18N.setLanguage.

parameters.display - Also note that if you still wish to have the study name built using the inputs in the key, but simply want to use a custom name instead of the type for the initial option, then set parameters.display. ie: if parameters.display is 'SAMPLE', the unique name would resemble "SAMPLE(param1,param2,param3,...)-X".

If both inputs.display and parameters.display are set, inputs.display will always take precedence.

You can directly set the display value on the study library entry for a new study, or extend an existing entry as follows:

CIQ.extend(CIQ.Studies.studyLibrary["rsi"],{inputs:{display:'YourCustomName'}});

An input can have one of the following value types:

  • Number (integer or decimal)
  • String
  • Boolean
  • Array of Strings

If the CIQ.Studies.DialogHelper object is used, there are a few shorthand values for inputs that can be utilized (as in the above example) to create an array of strings:

  • Literal “field” – will expand to an array of available fields in the dataset
  • Literal “ma” – will expand to an array of supported moving average types. Specifying a type of moving average (e.g., “vdma”) will do the same, but will default to the one specified. See “Adding a Moving Average Type” section below.

The unique id of a study instance is constructed using the inputs specified in this property.

calculateFN – Function which calculates the study results, also referred to as the “calculation function”.

This field is not strictly necessary, but omitting it indicates that the study does not perform any calculations because all resulting values are already present in the dataSet. This function will be discussed in more detail below.

outputs – Default colors and styles for each rendered study element.

*Set colors only

The colors can be expressed in either rgb, rgba, #hheexx or a web-friendly color name. Additionally, they can be set to “auto”, which allows the charting library itself to determine the appropriate color based on the chart theme. Outputs are not required, but if omitted, a default output of {"Result": "auto"} will be used.

"outputs": {"High":"#8cc176", "Low":"#b82c0c"}

*Set colors and styles

This feature is only available for line studies.

Two additional parameters are allowed along with color: width and pattern.

  • color is now its own field. All the rules in the previous section still apply.
  • width takes a number and determines how thick the line will be displayed. Defaults to 1.
  • pattern is the line dash pattern that will be displayed and takes one of the following values: solid, dotted, dashed. Defaults to solid.
"outputs": {"High": {color:"#8cc176", width:3, pattern:"dashed"}, "Low":{color:"#b82c0c", width:4, pattern: "dotted"}}

Here is a screenshot showing the outputs as defined above.

parameters – Default additional fields affecting the study’s rendering.

Some default studies support the specification of additional parameters. But you can add here any settings you need for your study; in addition to inputs and outputs.

There are 2 ways to use parameters: 1 - Any parameters specified within parameters.init will be copied into the study descriptor (sd.parameters) when the study is added, and included in the {CIQ.Studies.DialogHelper} returned object to be used in the study dialog.

Example:

        "ma": {
            "name": "Moving Average",
            "overlay": true,
            "calculateFN": CIQ.Studies.calculateMovingAverage,
            "inputs": {"Period":50,"Field":"field","Type":"ma","Offset":0},
            "outputs": {"MA":"#FF0000"},
            "parameters": {
                init:{
                    "panelName":"panel",
                    "underlayEnabled":false,
                    "yaxisDisplay":["right","left","none","shared"]
                }
            }            
        }

2 - Parameters not included in the parameters.init object, will remain in the sd.study.parameters object and can be used internally for your study logic, but will not be part of any menu.

The most common parameters supported deal with study zones for studies that render in a panel above or below the chart. A numerical value and color can be set for an over-bought and over-sold zone. The zones can also be enabled or disabled.

overlay – Whether the study will render over the chart or as a separate panel.

A value of true for this field indicates an overlay.

seriesFN – Function which renders the study results, also referred to as the “rendering function”.

Referencing a function here will allow a custom rendering of the study results on the chart. The results will appear either over the chart or in a separate panel, depending on the overlay property.

If this property is omitted, the results will be displayed as simple line plots, one for each field in the outputs property. If study zones are specified and overlay is not true, horizontal lines will be drawn at the zone levels and wherever results exceed the zone threshold the area between them will be shaded.

Note that the seriesFN function is called as part of the animation loop and should therefore be restricted to rendering computations. Any calculations of a study’s values which are dependent on quotefeed data should be put in the calculateFN function.

Convenience functions are available for the developer to use within seriesFN; they will be listed in a later section below.

Other properties are also available; they are listed in a table at the end of this tutorial.

The built-in study definitions can be found in chartiq.js. These files should not be modified directly. Instead, use CIQ.extend() function to add or modify entries to the studyLibrary.

Reference Table of avaialbe Study Definition elements

Property Purpose
appendDisplaySeriesAsLine Function which is executed after displaySeriesAsLine rendering function
attributes Input validation object
calculateFN Calculates study result values
centerline Draws a horizontal line in a panel at the value specified
customLegend Indicates whether study appears in the web component study legend
customRemoval Indicates a need to supply removal function for overlay in lieu of context highlight removal
deferUpdate Delay updating of inputs to a study until edit dialog is closed. Only applicalbe if WebComponents.cq-study-dialog is used.
edit Function to either disable or control editing of a study
horizontalCrosshairFieldFN Function which returns a field to snap crosshairs to on panel
initializeFN Function called when study first added or edited
inputs Fields used to qualify calculation function
isHighlighted Function to determine if mouse position is in the highlight zone
name Name to be shown in study dialog, menu, or other catalog of studies
outputs Fields used to specify rendering data, along with colors
overlay Indicates study is drawn over an existing panel
panelHeight Specify a height in pixels for a new study panel
parameters Fields used, generally, as inputs to the rendering function
permanent Indicates study cannot be removed or edited by user
range Sets the y-axis max and min values
removeFN Function called on study removal to clean up any resources created by study
renderer Array of renderers used to render the study if seriesFN is omitted.
seriesFN Function used to render the study
underlay Indicates study is drawn behind the existing panel
yAxis Object containing properties of the y-axis of the study
yAxisFN Function to draw a custom y-axis for the study panel

Next Steps: