ChartIQ SDK Legacy Documentation -

Namespace: Studies

STX. Studies

Namespace for functionality related to studies (aka indicators)

Classes

DialogHelper

Members

<static> actualOutputs :Array

Array of study outputs which should be considered valid fields in the study dialog "Field" dropdown". This is autopopulated from STX.Studies.displayStudies.

Type:
  • Array

<static> prettify :Object

Used to reduce certain common fields to abbreviated form for display in study panel labels

Type:
  • Object

<static> studyLibrary :Object

The studyLibrary defines all of the available studies. This is used to drive the dialog boxes and creation of the studies. When you create a custom study you should add it to the studyLibrary.

You can also alter study defaults by overriding the different elements on each definition. For example, if you wanted to change the default colors for the volume underlay, you would add the following code in your files; making sure your files are loaded after the library js files -- not before:

STX.Studies.studyLibrary["vol undr"].outputs= {"Up Volume":"blue","Down Volume":"yellow"};

See Custom Studies for complete details

Type:
  • Object
Example
"RAVI": {
				"name": "RAVI",
				"seriesFN": STX.Studies.displayRAVI,
				"calculateFN": STX.Studies.calculatePriceOscillator,
				"inputs": {"Field":"field", "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"}
				},
				"attributes":{"Short Cycle":{"min":1,"max":999,step:"1"}}
			},

<static> studyPanelMap :Object

Maps the names of studies to the panel that they are drawn on. For instance, a moving average may be drawn on an RSI panel

Type:
  • Object

Methods

<static> addStudy(stx, type [, inputs] [, outputs] [, parameters] [, panelName])

Adds or replace a study on the chart. A layout change event is triggered when this occurs.

Example:

Optionally you can assign the edit callback to a function that can handle initialization of a dialog box for editing studies. If the callback is not assigned a function, the edit study buttons/functionality will not appear. The 'Study Edit' feature is standard functionality in the advanced package.

Prior to version 2015-07-01, all edit functionality was handled by stx.editCallback and was limited to panel studies. Starting on version 2015-07-01, edit functionality is handled by stxx.callbacks.studyPanelEdit and stxx.callbacks.studyOverlayEdit; and it is available on both panel studies and overly studies. See Examples for exact function parameters and return value requirements. Please note that these callbacks must be set before you call importLayout. Otherwise your imported studies will not have an edit capability.

Parameters:
Name Type Argument Description
stx object

The chart object
type string

The name of the study (object key on the STX.Studies.studyLibrary)
inputs object <optional>

Inputs for the study instance. Default is those defined in the studyLibrary. Note that if you specify this object, it will not be combined with the library defaults. So even if you only want to define or override one single element (display, for example); you them must also send all of the additional inputs required to render the study.

Properties
Name Type Argument Description
id String <optional>

The id of the current study. If set, then the old study will be replaced
display String <optional>

The display name of the current study. If not set, a name generated by STX.Studies.prettyDisplay will be used. Note that if the study descriptor defines a display name, the study descriptor name will allays override this parameter.
outputs object <optional>

Outputs for the study instance. Default is those defined in the studyLibrary. Note that if you specify this object, it will not be combined with the library defaults. So even if you only want to override one single element; you them must also send all of the additional outputs required to render the study.
parameters object <optional>

Additional custom parameters for this study if supported or required by that study. Default is those defined in the STX.Studies.studyLibrary.

Properties
Name Type Argument Description
replaceID object <optional>

If inputs.id is specified, this value can be used to set the new ID for the modified study( will display as the study name on the study panel). If omitted the existing ID will be preserved..
panelName string <optional>

Optionally specify the panel. The relationship between studies and their panels is kept in STX.Studies.studyPanelMap. If not specified then an attempt will be made to locate a panel based on the input id or otherwise created if required.
Returns:

A study descriptor which can be used to remove or modify the study.

Type
object
Examples
STX.Studies.addStudy(stxx, "vol undr", {}, {"Up Volume":"#8cc176","Down Volume":"#b82c0c"});
// this is an example of  the expected stxx.editCallback function for version prior to version 2015-07-01
stxx.editCallback=function(stx, sd){
	// your code here
	return $$("studyDialog"); // This is a reference to the actual HTML dialog container that can be filled by studyDialog.
};
var params={stx:stx,sd:sd,inputs:inputs,outputs:outputs, parameters:parameters};
stxx.callbacks.studyPanelEdit=function(params){
		// your code here
};
var params={stx:stx,sd:sd,inputs:inputs,outputs:outputs, parameters:parameters};
stxx.callbacks.studyOverlayEdit=function(params){
		// your code here
};

<static> calculateCorrelationCoefficient(stx, sd)

Calculate function for correlation coefficient

Parameters:
Name Type Description
stx STXChart

Chart object
sd object

Study Descriptor
Version:
  • ChartIQ Advanced Package

<static> calculateGenericEnvelope(stx, sd, percentShift, centerIndex, offsetIndex, pointShift)

Calculate function for preparing data to be used by displayChannel(). Inserts the following fields in the dataSet: quote[sd.type + " Top " + sd.name]=quote[centerIndex]+totalShift;
quote[sd.type + " Bottom " + sd.name]=quote[centerIndex]-totalShift;
quote[sd.type + " Median " + sd.name]=quote[centerIndex];
quote["Bandwidth " + sd.name]=200totalShift/quote[centerIndex];
quote["%b " + sd.name]=50((quote.Close-quote[centerIndex])/totalShift+1);
 Example: 'Prime Bands' + ' Top ' + 'Prime Number Bands (true)'.

Parameters:
Name Type Description
stx STXChart

Chart object
sd object

Study Descriptor
percentShift object

Used to calculate totalShift. Defaults to 0 (zero)
centerIndex object

Quote element to use for center series (Open, Close, High, Low). Defaults to "Close"
offsetIndex object

Quote element to use for calculating totalShift (percentShift*quote[offsetIndex]+pointShift;)
pointShift object

Used to calculate totalShift.Defaults to 0 (zero)

<static> calculateKlinger(stx, sd)

Calculate function for klinger

Parameters:
Name Type Description
stx STXChart

Chart object
sd object

Study Descriptor

<static> calculateMACD(stx, sd)

Calculate function for MACD study

Parameters:
Name Type Description
stx STXChart

Chart object
sd object

Study Descriptor

<static> calculateMinMaxForDataPoint(stx, name, quotes)

Convenience function for determining the min and max for a given data point

Parameters:
Name Type Description
stx object

The chart
name string

The field to evaluate
quotes array

The array of quotes to evaluate (typically dataSet, scrubbed or dataSegment)

<static> calculateMovingAverage(stx, sd)

Calculate function for moving averages. sd.inputs["Type"] can be used to request a specific type of moving average.

Parameters:
Name Type Description
stx STXChart

Chart object
sd object

Study Descriptor

<static> calculateMovingAverageExponential(stx, sd)

Calculate function for exponential moving average

Parameters:
Name Type Description
stx STXChart

Chart object
sd object

Study Descriptor

<static> calculateMovingAverageTimeSeries(stx, sd)

Calculate function for time series moving average

Parameters:
Name Type Description
stx STXChart

Chart object
sd object

Study Descriptor

<static> calculateMovingAverageTriangular(stx, sd)

Calculate function for triangular moving average

Parameters:
Name Type Description
stx STXChart

Chart object
sd object

Study Descriptor

<static> calculateMovingAverageVariable(stx, sd)

Calculate function for variable moving average and VI Dynamic MA (VIDYA)

Parameters:
Name Type Description
stx STXChart

Chart object
sd object

Study Descriptor

<static> calculatePriceRelative(stx, sd)

Calculates data for Price Relative Study

Parameters:
Name Type Description
stx object

The chart object
sd object

The study descriptor object
Version:
  • ChartIQ Advanced Package

<static> calculateRSI()

A sample study calculation function. Note how sd.chart.scrubbed is used instead of dataSet. Also note the naming convention for the outputs.

<static> calculateStandardDeviation(stx, sd)

Calculate function for standard deviation.

Parameters:
Name Type Description
stx STXChart

Chart object
sd object

Study Descriptor

<static> calculateStochastics(stx, sd)

Calculate function for stochastics

Parameters:
Name Type Description
stx STXChart

Chart object
sd object

Study Descriptor

<static> calculateVolume()

A simple calculation function. Volume is already obtained, so all that is done here is setting colors.

<static> createHistogram(stx, sd, quotes, centered [, opacity])

Draws a histogram on the study. Initial bar color is defined in stx-chart.css under '.stx_histogram'. If using the default UI, refer to stx-standard.css under '.Light .stx_histogram' and '.Dark .stx_histogram' style sections. If sd.outputs["Decreasing Bar"] and sd.outputs["Increasing Bar"] are present, their corresponding colors will be used instead.

Note the convention to use sd.name+"_hist" for histogram values on a study

Parameters:
Name Type Argument Default Description
stx object

The chart object
sd object

The study descriptor
quotes array

The quotes (dataSegment)
centered boolean

If true then the histogram will be physically centered on the yAxis, otherwise it will be centered at the zero value on the yAxis
opacity number <optional>
 1

Optionally set the opacity

<static> createVolumeChart()

Creates a volume chart. This is the one study that requires a specific panel name called "vchart". If no volume is available on the screen then the panel will be watermarked "Volume Not Available" (translated if a translate function is attached to the kernel object). Will use color attributes from the CSS styles stx_volume_up and stx_volume_down unless overwritten by the calculation function ( default behavior).

<static> createYAxis(stx, sd, quotes, panel)

Creates the yAxis for a study panel. Utilizes STXChart.createYAxis internally. This method is not re-entrant. panel.axisDrawn will be set to true in order to prevent the yAxis from being drawn multiple times if there are multiple studies on a panel. The first study on the panel will therefore determine the minimum and maximum bounds of the panel. If the library entry defines a yAxisFN function then it will be used to render the yaxis instead of STXChart.createYAxis. If zones are enabled then STXChart.createYAxis again will not be the renderer.

Parameters:
Name Type Description
stx object

The chart object
sd object

The study descriptor
quotes array

The set of quotes (representing dataSegment)
panel object

A reference to the panel

<static> determineMinMax(stx, sd, quotes)

Method to determine the minimum and maximum points in a study panel. The studyLibrary is checked for the type of range. If the range is dynamic then the output values for the study are checked for minimum and maximum values. If a histogram is being printed then the values for the histogram (represented by sd.name+"_hist") are also checked. This method does not draw the yAxis but it does compute the high, low and shadow that the yAxis utilizes when drawn.

Parameters:
Name Type Description
stx object

The chart object
sd object

The study descriptor
quotes array

The set of quotes to evaluate

<static> displayChannel(stx, sd, quotes)

Rendering function for displaying a Channel study output composed of top, middle and bottom lines.

Requires study library input of "Channel Fill":true to determine if the area within the channel is to be shaded. Shading will be done using the "xxxxx Channel" or "xxxxx Median" color defined in the outputs parameter of the study library.

Requires study library outputs to have fields in the format of :

  • 'xxxxx Top' or 'xxxxx High' for the top band,
  • 'xxxxx Bottom' or 'xxxxx Low' for the bottom band and
  • 'xxxxx Median' or 'xxxxx Channel' for the middle line.

It expects 'quotes' to have fields for each series in the channel with keys in the following format:

  • study-output-name ( from study library) + " " + sd.name.
  • Example: 'Prime Bands Top'+ ' ' + 'Prime Number Bands (true)'. Which equals : 'Prime Bands Top Prime Number Bands (true)'
Parameters:
Name Type Description
stx STXChart

Chart object
sd object

Study Descriptor
quotes array

The array of quotes needed to render the channel
Example
"inputs": {"Period":5, "Shift": 3, "Field":"field", "Channel Fill":true}
"outputs": {"Prime Bands Top":"red", "Prime Bands Bottom":"auto", "Prime Bands Channel":"rgb(184,44,11)"}

<static> displayHistogramWithSeries(stx, sd, quotes)

A sample of a custom display function. This function creates the yAxis, draws a single histogram and then plots the series. Note that to differentiate between a regular series and the histogram series there is a convention to use sd.name+"_hist" for histogram values on a study See STX.Studies.createHistogram for details

Parameters:
Name Type Description
stx object

The chart object
sd object

The study descriptor
quotes array

The quotes (dataSegment)

<static> displayIndividualSeriesAsLine(stx, sd, panel, name, quotes)

Displays multiple data-points as series on a panel. This is the default display function for an indicator and will work for 90% of custom indicators. It also inserts the study results into the studyPanelMap to be selected as the basis for another study.

Parameters:
Name Type Description
stx object

The chart object
sd object

The study descriptor
panel object

A reference to the study panel
name string

The name of this study instance (should match field from 'quotes' needed to render this line)
quotes array

The array of quotes (dataSegment)

<static> displayPSAR2()

A sample display function for an overlay. An overlay displays in the chart area.

Also note the use of clipping to ensure that the overlay doesn't print outside of the panel

Finally note that when color=="auto" you can use stx.defaultColor which will automatically adjust based on the background color. This is the default for studies that use the color picker for user selection of output colors.

<static> displaySeriesAsHistogram(stx, sd, quotes)

Displays a single or group of series as histogram in the study panel. It expects the 'quotes' array to have data fields for each series with keys in the outputMap format: 'output name from study library'+ " " + sd.name.

It takes into account the following study input fields (see STXChart#drawHistogram for details ) :

  • sd.inputs.HistogramType ("overlaid", "clustered", "stacked") - Default "overlaid"
  • sd.inputs.HeightPercentage - Default ".25"
  • sd.inputs.WidthFactor - Default ".5"
Parameters:
Name Type Description
stx object

The chart object
sd object

The study descriptor
quotes array

The set of quotes (dataSegment)
Example
// this adds a study panel that will display the High and Low values from the masterData as a stacked histogram study
STX.Studies.studyLibrary["Plot High Low"]={
 	"seriesFN": STX.Studies.displaySeriesAsHistogram,
 	inputs:{"HistogramType":"stacked"},
    outputs:{"High":"blue","Low":"red"}
};
STX.Studies.quickAddStudy(stxx, "Plot High Low");

<static> displaySeriesAsLine(stx, sd, quotes)

Displays a single or group of series as lines in the study panel. One series per output field declared in the study library will be displayed. It expects the 'quotes' array to have data fields for each series with keys in the outputMap format: 'output name from study library'+ " " + sd.name. Y-axis will be rendered if studyOverZones are not set and panel is not “hidden”. studyOverZones will be displayed and Peaks & Valleys will be filled if corresponding thresholds are set in the study library as follows:

init:{studyOverZonesEnabled:true, studyOverBoughtValue:70, studyOverBoughtColor:"auto", studyOverSoldValue:30, studyOverSoldColor:"auto"}

For most custom studies this function will do the work for you.

Parameters:
Name Type Description
stx object

The chart object
sd object

The study descriptor
quotes array

The set of quotes (dataSegment)

<static> displayStudies(stx, chart [, underlays])

Animation Loop This method displays all of the studies for a chart. It is called from within the chart draw() loop.

Parameters:
Name Type Argument Default Description
stx STXChart

The charting object
chart STXChart.Chart

Which chart to display studies for
underlays Boolean <optional>
 false

If set to true then underlays only will be displayed, otherwise underlays will be skipped

<static> drawHorizontal(stx, sd, quotes, price)

Draws a horizontal line on the study.

Parameters:
Name Type Description
stx object

The chart object
sd object

The study descriptor
quotes array

The array of quotes (unused)
price number

The price (value) to draw the horizontal line

<static> fillArea(stx, points, color, opacity [, panelName])

Fills an area on the chart, usually created by a study.

Parameters:
Name Type Argument Description
stx object

The chart object
points array

The set of points, this is an array of chart coordinates in array form e.g. [[x1,y1],[x2,y2]]. The points should be arranged to form a loop; the loop need not be closed.
color string

color to fill the area
opacity number

opacity of fill, 0 to 1. Defaults to 0.1
panelName string <optional>

optional Name of panel to draw on. If omitted or invalid, area may fill over top or bottom of plot area
Since:
  • panelName parameter added 01-20-2015

<static> generateID(stx, studyName, inputs [, replaceID])

Automatically generates a unique name for the study instance. If a translation callback has been associated with the chart object then the name of the study will be translated.

Parameters:
Name Type Argument Description
stx object

A chart object
studyName string

Type of study
inputs object

The inputs for this study instance
replaceID string <optional>

If it matches then return the same id
Returns:

A unique name for the study

Type
string

<static> getCustomParameters(div, parameters)

This method parses out custom parameters from the study dialog. For this to work, the studyLibrary entry must contain a value "parameters". This object should then include a "template" which is the id of the html element that is appended to the studyDialog. Then another object "init" should contain all of the id's within that template which contain data. It is currently used to create "zones" in study panels.

Parameters:
Name Type Description
div object

The study dialog window
parameters object

An object containing the parameters to set in the study dialog window. These parameters would typicaly come from the study descriptor (library entry).

<static> go(div, stx)

Converts a study dialog into an actual study. Study Dialogs must follow a specific UI format (@see STX.Studies.studyDialog) in order for this function to operate correctly. Typically it will be called when a user clicks the "submit" button on an HTML study dialog window.

Parameters:
Name Type Description
div object

The DOM element that is the study dialog
stx object

A chart object
Returns:

The study descriptor is returned. This can be used in the future for deleting the study programatically.

Type
object

<static> initializeFN(stx, type, inputs, outputs [, parameters] [, panelName])

The default initialize function for a study. It creates the study descriptor. It creates the panel if one is required.

Parameters:
Name Type Argument Description
stx object

The chart object
type string

The type of study (from studyLibrary)
inputs object

The inputs for the study instance
outputs object

The outputs for the study instance
parameters object <optional>

Optional parameters if required or supported by this study
panelName string <optional>

Optional panel. If not provided then the panel will be determined dynamically.
Returns:

The newly initialized study descriptor

Type
object

<static> initializeStochastics()

A sample of a custom initialize function. It is rare that one would be required. In this case we simply customize the input display but otherwise call the default.

<static> MA(type, periods, field, offset, name, stx, sd)

Moving Average convenience function

Parameters:
Name Type Description
type string

The type of moving average, e.g. simple, exponential, triangular, etc
periods number

Moving average period
field string

The field in the data array to perform the moving average on
offset number

Periods to offset the result by
name string

String to prefix to the name of the output. Full name of output would be name + " " + sd.name, for instance "Signal MACD"
stx STXChart

Chart object
sd object

Study Descriptor
Since:
  • 04-2015

<static> movingAverageHelper(stx, input)

Does conversions for valid moving average types

Parameters:
Name Type Description
stx STXChart

The chart object
input String

String to test if a moving average type or "options" to return the list of ma options.
Returns:

The name of the moving average or a list of options

Type
Object

<static> parseDialog(div, stx)

Extracts the user input data from a study dialog. Study Dialogs must follow a specific UI format (@see STX.Studies.studyDialog) in order for this function to operate correctly. Typically it will be called from the go() function (@see STX.Studies.go).

Parameters:
Name Type Description
div object

The DOM element that is the study dialog
stx object

A chart object
Since:
  • 04-2015
Returns:

A pseudo-study descriptor is returned. It contains only the input, output, and parameters objects.

Type
object

<static> prettyDisplay(id)

Convert a study ID into a displayable format

Parameters:
Name Type Description
id string

The ID
Returns:

A pretty (shortened) ID

Type
string

<static> quickAddStudy(stx, studyName, inputs [, outputs] [, parameters])

A convenience function for programatically adding a study.

Example:

Parameters:
Name Type Argument Description
stx object

The chart object
studyName string

The name of the study (out of the studyLibrary)
inputs object

The input values for this study instance ( for exact values used in each study, see STX.Studies.studyLibrary)
outputs object <optional>

Output colors ( for exact values used in each study, see STX.Studies.studyLibrary)
parameters object <optional>

Custom parameters if the study requires/supports them
Deprecated:
  • Use STX.Studies.addStudy
Returns:

Returns a study descriptor which can be used to delete or modify the study.

Type
object

<static> removeStudy(stx, sd)

Removes a study from the chart (and panel if applicable)

Parameters:
Name Type Description
stx object

A chart object
sd object

A study descriptor returned from STX.Studies.quickAddStudy or STX.Studies.go

<static> StudyDescriptor(name, type, panel, inputs, outputs, parameters)

A study descriptor contains all of the information necessary to instantiate a study.

Parameters:
Name Type Description
name string

The name of the study. This should be unique to the chart. For instance if there are two RSI panels then they should be of different periods and named accordingly. Usually this is determined automatically by the library.
type string

The type of study, which can be used as a look up in the StudyLibrary
panel string

The name of the panel that contains the study
inputs object

Names and values of input fields
outputs object

Names and values (colors) of outputs
parameters object

Additional parameters that are unique to the particular study

<static> studyDialog(stx, study, div [, override])

Renders a study dialog in standard form. The study dialog must be of specific format as provided in sample html files.

Parameters:
Name Type Argument Description
stx object

Chart object
study string

Study type (as in studyLibrary)
div object

The study dialog DOM element which should already exist in the HTML
override object <optional>

Optional input and output map to override the defaults (used when editing existing study)

Properties
Name Type Argument Description
inputs object <optional>

Override inputs
outputs object <optional>

Override outputs
parameters object <optional>

Override additional parameters

<static> volumeChart(stx, sd, colorMap, borderMap)

Convenience function for creating a volume style chart that supports multiple colors of volume bars. If borderMap (border colors) is passed in then the chart will display in a format where bars are flush against one another so that there is no white space between bars. If however a borderMap is not specified then white space will be left between the bars.

Parameters:
Name Type Description
stx STXChart

The chart object
sd object

The study descriptor
colorMap object

Map of colors to arrays. Each array should contain entries for each dataSegment bar mapped to that color. It should contain null values for any bar that shouldn't be drawn
borderMap object

Map of border colors for each color. If null then no borders will be drawn.
Example
var colorMap={};
colorMap["#FF0000"]=[56,123,null,null,45];
colorMap["#00FF00"]=[null,null,12,13,null];

var borderMap={
   "#FF0000": "#FFFFFF",
   "#00FF00": "#FFFFDD"
};
STX.Studies.volumeChart(stx, sd, colorMap, borderMap);

<static> volUnderlay()

Creates a volume underlay for the chart. The underlay is always 25% of the height of the chart. Will use color attributes from the CSS styles stx_volume_underlay_up and stx_volume_underlay_down unless overwritten by the calculation function ( default behavior).