Namespace: Studies

CIQ. Studies

Namespace for functionality related to studies (aka indicators).

See Using and Customizing Studies for additional details and a general overview about studies.

Classes

DialogHelper
StudyDescriptor

Members


<static> DEFAULT_INPUTS

Constants for when no inputs or outputs specified in studies. Values can be changed but do not change keys.


<static> prettify :Object

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

Type:
  • Object

Methods


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

Adds or replaces a study on the chart.

A layout change event is triggered when this occurs.

See Using and Customizing Studies for more details.

Example:

Optionally you can define an edit event listeners to call a custom function that can handle initialization of a dialog box for editing studies.

  • Use studyPanelEditEventListener to link the cog wheel on study panels to your desired edit menu/functionality.
  • Use studyOverlayEditEventListener to link the right click on study overlays to your desired edit menu/functionality.
  • All studies will use the same function set by the event listeners.
  • If there are no event listeners set, the edit study buttons/functionality will not appear.
  • The 'Study Edit' feature is standard functionality in the advanced sample template.
  • See Examples section for exact function parameters and return value requirements.
  • Please note that these listeners must be set before you call importLayout. Otherwise your imported studies will not have an edit capability.

Use the CIQ.Tooltip addOn if you wish to display values on mouse hover.
Alternatively, you can create your own Heads-Up-Display (HUD) using this tutorial: Custom Heads-Up-Display (HUD)

Parameters:
Name Type Argument Description
stx CIQ.ChartEngine

The chart object

type string

The name of the study (object key on the CIQ.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 be combined with (override) the library defaults. To bypass a library default, set that field to null.

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 CIQ.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. Values specified here will override those in the studyLibrary.

parameters object <optional>

Additional custom parameters for this study if supported or required by that study. Default is those defined in the CIQ.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.

display object <optional>

If this is supplied, use it to form the full study name. Otherwise studyName will be used. Is both inputs.display and parameters.display are set, inputs.display will always take precedence.
ie: if custom name is 'SAMPLE', the unique name returned would resemble "SAMPLE(param1,param2,param3,...)-X".

calculateOnly object <optional>

Only setup the study for calculations and not display. If this is supplied, UI elements will not be added.

panelName string <optional>

Optionally specify the panel.
This must be an existing panel (see example).
If set to "New panel" a new panel will be created for the study. If not specified or an invalid panel name is provided, then an attempt will be made to locate a panel based on the input id or otherwise created if required. Multiple studies can be overlaid on any panel.

study object <optional>

Study definition, overriding what may be found in the study library

Since:
  • 3.0.0 Added study parameter.
  • 5.1.1 Added parameters.display. If this parameter is supplied, use it to form the full study name.
  • 5.2.0 Multiple studies can be overlaid on any panel using the panelName parameter.
  • 7.1.0 Changed specification for a new panel in panelName from "Own panel" to "New panel".
Deprecated:
  • Since 6.3.0 panelName argument is deprecated but maintained for backwards compatibility. Use parameters.panelName instead.

Returns:

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

Type
studyDescriptor
Examples

Add a volume underlay study with custom colors:

CIQ.Studies.addStudy(stxx, "vol undr", {}, { "Up Volume": "#8cc176", "Down Volume": "#b82c0c" });

Define the edit function for study Panels:

var params = { stx: stx, sd: sd, inputs: inputs, outputs: outputs, parameters: parameters };
stxx.addEventListener("studyPanelEdit", function (studyData) {
	// your code here
});

Define the edit function for study overlays:

stxx.addEventListener("studyOverlayEdit", function (studyData) {
	CIQ.alert(studyData.sd.name);
	var helper = new CIQ.Studies.DialogHelper({ name: studyData.sd.type, stx: studyData.stx });
	console.log("Inputs:", JSON.stringify(helper.inputs));
	console.log("Outputs:", JSON.stringify(helper.outputs));
	console.log("Parameters:", JSON.stringify(helper.parameters));
	// call your menu here with the  data returned in helper
	// modify parameters as needed and call addStudy or replaceStudy
});

Add an Aroon study with a custom display name:

CIQ.Studies.addStudy(stxx, "Aroon", null, null, { display: "Custom Name" });

Add multiple studies to the same panel.

// create your panel
stxx.createPanel("New Panel", "new_panel");
// add your studies to it.
CIQ.Studies.addStudy(stxx, "ma", null, null, { panelName: "new_panel" });
CIQ.Studies.addStudy(stxx, "Aroon", null, null, { panelName: "new_panel" });

<static> calculateCorrelationCoefficient(stx, sd)

Calculate function for correlation coefficient

Parameters:
Name Type Description
stx CIQ.ChartEngine

Chart object

sd object

Study Descriptor


<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]=200*totalShift/quote[centerIndex];
quote["%b " + sd.name]=50*((quote.Close-quote[centerIndex])/totalShift+1);

Example: 'Prime Bands' + ' Top ' + 'Prime Number Bands (true)'.

Parameters:
Name Type Argument Default Description
stx CIQ.ChartEngine

Chart object

sd studyDescriptor

Study Descriptor

percentShift object

Used to calculate totalShift. Defaults to 0 (zero)

centerIndex object <optional>
Close

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

offsetIndex object <optional>
centerIndex

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 CIQ.ChartEngine

Chart object

sd studyDescriptor

Study Descriptor


<static> calculateMACD(stx, sd)

Calculate function for MACD study.

The resulting values will be added to the dataSet using the field name provided by the sd.outputMap entry.

Notes:

  • If no outputs object is defined in the library entry, the study will default to a single output named Result, which will then be used in lieu of sd.outputs to build the sd.outputMap.
  • The study name may contain the unprintable character &zwnj;, see studyDescriptor documentation
  • Results for the histogram will be added to the dataSegment using a field composed the study name and the "_hist" suffix.
Parameters:
Name Type Description
stx CIQ.ChartEngine

Chart object

sd studyDescriptor

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 CIQ.ChartEngine

The chart

name string

The field to evaluate

quotes array

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

Returns:

Object containing the min and max data point values

Type
object

<static> calculateMovingAverage(stx, sd)

Calculate function for moving averages.

sd.inputs["Type"] can be used to request a specific type of moving average. Valid options can be seen by inspecting the keys on the CIQ.Studies.movingAverage.typeMap object.

The resulting values will be added to the dataSet using the field name provided by the sd.outputMap entry.

Notes:

  • This function calculates a single value, so it expects sd.outputMap to contain a single mapping.
  • To leverage as part of a larger study calculation, use CIQ.Studies.MA instead.
  • If no outputs object is defined in the library entry, the study will default to a single output named Result, which will then be used in lieu of sd.outputs to build the field name.
  • The study name may contain the unprintable character &zwnj;, see studyDescriptor documentation.
Parameters:
Name Type Description
stx CIQ.ChartEngine

A chart engine instance

sd studyDescriptor

A study descriptor


<static> calculatePriceRelative(stx, sd)

Calculates data for Price Relative Study

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

sd object

The study descriptor object


<static> calculateProjectedVolume(stx, sd)

Calculates the projections and aggregations for the Projected Volume at Time (PVAT) and Projected Aggregate Volume (PAV) studies. Due to the data requirements of the studies, this function may attempt to use the quote feed to fetch additional historical data. If no quote feed is available and not enough data has been loaded, the study displays an error.

The studies support intraday periodicities of 1 minute and higher. Aggregations other than Heiken-Ashi are not supported.

Only days when the market is open are included in the volume average. If the lookback includes days with restricted market hours, the non-open periods are ignored, producing an average with fewer data points.

Parameters:
Name Type Description
stx CIQ.ChartEngine

A reference to the chart object.

sd studyDescriptor

Specifies the study (PVAT or PAV) for which the projected volume is calculated.

Since:
  • 8.0.0


<static> calculateRateOfChange(stx, sd)

Calculate function for Rate Of Change related studies. Price ROC, Volume ROC and Momentum.

The resulting values will be added to the dataSet using the field name provided by the sd.outputMap entry.

Notes:

  • This function calculates a single value, so it expects sd.outputMap to contain a single mapping.
  • If no outputs object is defined in the library entry, the study will default to a single output named Result, which will then be used in lieu of sd.outputs to build the field name.
  • The study name may contain the unprintable character &zwnj;, see studyDescriptor documentation.
Parameters:
Name Type Description
stx CIQ.ChartEngine

Chart object

sd studyDescriptor

Study Descriptor


<static> calculateRSI(stx, sd)

Default study calculation function for RSI study.

The resulting values will be added to the dataSet using the field name provided by the sd.outputMap entry.

Notes:

  • This function calculates a single value, so it expects sd.outputMap to contain a single mapping.
  • If no outputs object is defined in the library entry, the study will default to a single output named Result, which will then be used in lieu of sd.outputs to build the field name.
  • The study name may contain the unprintable character &zwnj;, see studyDescriptor documentation.
Parameters:
Name Type Description
stx CIQ.ChartEngine

A chart engine instance

sd studyDescriptor

A study descriptor

Since:
  • 6.3.0 RSI can now be calculated on any field instead of just "Close".


<static> calculateStandardDeviation(stx, sd)

Calculate function for standard deviation.

The resulting values will be added to the dataSet using the field name provided by the sd.outputMap entry.

Notes:

  • If no outputs object is defined in the library entry, the study will default to a single output named Result, which will then be used in lieu of sd.outputs to build the sd.outputMap.
  • The study name may contain the unprintable character &zwnj;, see studyDescriptor documentation
Parameters:
Name Type Description
stx CIQ.ChartEngine

Chart object

sd studyDescriptor

Study Descriptor


<static> calculateStochastics(stx, sd)

Calculate function for stochastics

Parameters:
Name Type Description
stx CIQ.ChartEngine

Chart object

sd studyDescriptor

Study Descriptor


<static> calculateTypicalPrice(stx, sd)

Calculate function for Typical Price studies. Median Price, Typical Price and Weighted Close.

The resulting values will be added to the dataSet using the field name provided by the sd.outputMap entry.

Notes:

  • This function calculates a single value, so it expects sd.outputMap to contain a single mapping.
  • If no outputs object is defined in the library entry, the study will default to a single output named Result, which will then be used in lieu of sd.outputs to build the field name.
  • The study name may contain the unprintable character &zwnj;, see studyDescriptor documentation.
Parameters:
Name Type Description
stx CIQ.ChartEngine

Chart object

sd studyDescriptor

Study Descriptor


<static> calculateValuationLines(stx, sd, quotes)

Calculate "val lines" study. This study does all calculations on the {studyDescriptor.chart.dataSegment}.

Parameters:
Name Type Description
stx CIQ.ChartEngine

A chart engine instance

sd studyDescriptor

A study descriptor

quotes Array.<Object>

the dataSegment


<static> calculateVolume(stx, sd)

Default Volume calculation function.

Volume is already obtained, so all that is done here is setting colors.

Parameters:
Name Type Description
stx CIQ.ChartEngine

A chart engine instance

sd studyDescriptor

Study to calculate volume for


<static> calculateVWAP(stx, sd)

Calculate function for VWAP.

Cumulative values are calculated on a daily basis. The start of the day is calculated based on the particular market start time. As such, you may need to review your market definitions and symbology for this study to properly work with your data as the default assumptions may not totally match. More information on setting market hours and symbology rules can be found here: CIQ.Market

In our calculations, the beginning of the Forex day is 17:00 NY Time. The chart will be adjusted as needed to reflect this time in the browser time zone (or any specificaly set display zone).

Parameters:
Name Type Description
stx CIQ.ChartEngine

Chart object

sd object

Study Descriptor

Since:
  • 7.0.0 Used for AVWAP calculation as well.


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

Method used to display a histogram, which can be centered at the zero value.

Used in studies such as on the "MACD" and "Klinger Volume Oscillator".

Initial bar color is defined in stx-chart.css under '.stx_histogram'.
If using the default UI, refer to provided css files under '.stx_histogram' and '.ciq-night .stx_histogram' style sections.
If sd.outputs["Decreasing Bar"], sd.outputs["Negative Bar"], sd.outputs["Increasing Bar"] and sd.outputs["Positive 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 CIQ.ChartEngine

The chart object

sd studyDescriptor

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

Example

Draws a histogram with alternating bid and ask records. Bids are positive, asks are negative.

CIQ.Studies.calculateBidAsk = function (stx, sd) {
	var quotes = sd.chart.scrubbed;
	var name = sd.name;

	var histogram = name + "_hist";
	for (i = 0; i < quotes.length; i++) {
		quote = quotes[i];
		i % 2 ? (quote[histogram] = quote.Bid) : (quote[histogram] = quote.Ask * -1);
	}
};

CIQ.Studies.studyLibrary["Plot BidAsk"] = {
	seriesFN: CIQ.Studies.createHistogram,
	calculateFN: CIQ.Studies.calculateBidAsk,
	outputs: { "Negative Bar": "red", "Positive Bar": "green" },
};

CIQ.Studies.addStudy(stxx, "Plot BidAsk");

<static> createLibraryHash()

Computes a hash of the study library keys. The hash can be assigned to a property so that studyLibrary changes can be observed. This function is automatically called in the draw loop.

Since:
  • 7.2.0

Returns:

A hash of studyLibrary keys.

Type
string

<static> createVolumeChart(stx, sd, quotes)

Creates a volume chart.

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).

Uses CIQ.ChartEngine#drawHistogram and any "parameters" in the study definition will send into its 'params' object to control the histogram look and feel.
Example:

CIQ.extend(CIQ.Studies.studyLibrary["vol undr"],{
		"parameters": {
			"widthFactor":0.5
		}
});

Uses CSS style :

  • stx_volume_underlay if "sd.underlay" is true
  • stx_volume if "sd.underlay" is NOT true

See CIQ.ChartEngine#colorByCandleDirection to base colors on difference between open and close vs. difference between previous close and close.

Parameters:
Name Type Description
stx CIQ.ChartEngine

A chart engine instance

sd studyDescriptor

A study descriptor

quotes array

Array of quotes

Examples
{
	// default volume study library entry with required parameters
	"volume": {
		"name": "Volume Chart",
		"range": "0 to max",
		"yAxis": { "ground": true, "initialMarginTop": 0, "zoom": 0 },
		"seriesFN": CIQ.Studies.createVolumeChart,
		"calculateFN": CIQ.Studies.calculateVolume,
		"inputs": {},
		"outputs": { "Up Volume": "#8cc176", "Down Volume": "#b82c0c" }
	}
}
{
	// default volume underlay library entry with required parameters
	"vol undr": {
		"name": "Volume Underlay",
		"underlay": true,
		"range": "0 to max",
		"yAxis": {
			"ground": true,
			"initialMarginTop": 0,
			"position": "none",
			"zoom": 0,
			"heightFactor": 0.25
		},
		"seriesFN": CIQ.Studies.createVolumeChart,
		"calculateFN": CIQ.Studies.calculateVolume,
		"inputs": {},
		"outputs": { "Up Volume": "#8cc176", "Down Volume": "#b82c0c" },
		"customRemoval": true,
		"removeFN": function (stx, sd) {
			stx.layout.volumeUnderlay = false;
			stx.changeOccurred("layout");
		},
		"attributes": {
			"panelName": { "hidden": true }
		}
	}
}

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

Creates the yAxis for a study panel.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

sd studyDescriptor

The study descriptor

quotes array

The set of quotes (representing dataSegment)

panel CIQ.ChartEngine.Panel

A reference to the panel

Deprecated:
  • Since 5.2.0. yAxis is now created automatically via CIQ.ChartEngine#renderYAxis


<static> determineColor(output)

A helper function that will find the color value in the output.

Parameters:
Name Type Description
output String/Object

Color string value or object that has the color value

Since:
  • 4.0.0

Returns:

Color value

Type
string

<static> determineMinMax(stx, sd, quotes)

Deprecated since 5.2.0. This calculation is now done in CIQ.ChartEngine.AdvancedInjectable#initializeDisplay and is no longer a separate function.

Method to determine the minimum and maximum points in a study panel.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

sd studyDescriptor

The study descriptor

quotes array

The set of quotes to evaluate

Deprecated:

<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 CIQ.ChartEngine

Chart object

sd studyDescriptor

Study Descriptor

quotes array

The array of quotes needed to render the channel

Since:
  • 4.1.0 Now also uses sd.parameters.opacity if one defined.
  • 4.1.0 Now shading is rendered under the channel lines instead of over.
Examples
"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)"}
{
	// full definition example including opacity
	"Bollinger Bands": {
		"name": "Bollinger Bands",
		"overlay": true,
		"calculateFN": CIQ.Studies.calculateBollinger,
		"seriesFN": CIQ.Studies.displayChannel,
		"inputs": {
			"Field": "field",
			"Period": 20,
			"Standard Deviations": 2,
			"Moving Average Type": "ma",
			"Channel Fill": true
		},
		"outputs": {
			"Bollinger Bands Top": "auto",
			"Bollinger Bands Median": "auto",
			"Bollinger Bands Bottom": "auto"
		},
		"attributes": {
			"Standard Deviations": { "min": 0.1, "step": 0.1 }
		},
		"parameters": {
			"init": { "opacity": 0.2 }
		}
	}
}

<static> displayError(stx, sd [, params])

Displays a watermark on a panel for a study with sd.error set.

The sd.error property can be set to true, which will display the default message "Not enough data to compute XXX", or it can be set to a custom string which will be displayed as supplied.

Parameters:
Name Type Argument Description
stx CIQ.ChartEngine

The charting object.

sd studyDescriptor

The study descriptor.

params Object <optional>

Additional options to customize the watermark.

Properties
Name Type Argument Description
panel string <optional>

Name of the panel on which to display the error, defaults to sd.panel.

h string <optional>

Watermark horizontal position.

v string <optional>

Watermark vertical position.

Since:
  • 3.0.0
  • 4.0.0 Displays one error per panel. Added params object.
  • 7.3.0 Errors without params or in center bottom, use CIQ.ChartEngine#displayErrorAsWatermark instead of CIQ.ChartEngine#watermark, which stacks errors vertically to prevent errors overlaying other errors. Any other positioning is deprecated and results in multiple errors at that location getting stacked on the z-axis.

<static> displayHistogramWithSeries(stx, sd, quotes)

Method used to display series together with a histogram centered at the zero value.

Used in studies such as on the "MACD" and "Klinger Volume Oscillator".

This function creates the yAxis, draws a single histogram and then plots series, multiple if needed.

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 CIQ.Studies.createHistogram for details and examples.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

sd studyDescriptor

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.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

sd studyDescriptor

The study descriptor.

Set the following elements to customize behavior (see example):

panel CIQ.ChartEngine.Panel

A reference to the study panel

name string

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

quotes array

The array of quotes (dataSegment)

Since:
  • 5.2.0 The number of decimal places for the y-axis is determined by the distance between ticks as opposed to shadow.

Example
var study = {
	overlay: true,
	yAxis: {},
	parameters: {
		plotType: "step",
	},
	seriesFN: function (stx, sd, quotes) {
		sd.extendToEnd = false;
		(sd.gaplines = false), CIQ.Studies.displaySeriesAsLine(stx, sd, quotes);
	},
};
CIQ.Studies.addStudy(stxx, "Vol", {}, { Volume: "green" }, null, null, study);

<static> displayProjectedVolume(stx, sd, quotes)

Displays the Projected Volume at Time (PVAT) and Projected Aggregate Volume (PAV) studies.

Parameters:
Name Type Description
stx CIQ.ChartEngine

A reference to the chart object.

sd studyDescriptor

Specifies the study (PVAT or PAV) to be displayed.

quotes array

An array of quotes from which the study is constructed.

Since:
  • 8.0.0


<static> displayPSAR2(stx, sd, quotes)

Default display function used on 'ATR Trailing Stop' and 'Parabolic SAR' studies to display a series of 'dots' at the required price-date coordinates.

Visual Reference:
displayPSAR2

Parameters:
Name Type Description
stx CIQ.ChartEngine

A chart engine instance

sd studyDescriptor
quotes array

Array of quotes


<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 fields (see CIQ.ChartEngine#drawHistogram for details):

  • sd.inputs.HistogramType — "overlaid", "clustered", or "stacked". Default "overlaid".
  • sd.outputs — Can contain a color string or an object containing {color, opacity}. Default opacity ".3".
  • sd.parameters.widthFactor — Default ".5".
Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object.

sd studyDescriptor

The study descriptor.

quotes array

The set of quotes (dataSegment).

Since:
Example

Adds a study panel that will display the High and Low values from the masterData as a clustered histogram study.

CIQ.Studies.studyLibrary["Plot High Low"]={
    "seriesFN": CIQ.Studies.displaySeriesAsHistogram,
    inputs:{"HistogramType":["clustered","stacked","overlaid"]},
    outputs:{"High":"blue","Low":{color:"red",opacity:0.7},
    parameters:{"widthFactor":0.5},
    range: "0 to max",
    yAxis:{"ground":true,"initialMarginTop":0,"zoom":0, "heightFactor":0.5}
};
CIQ.Studies.addStudy(stxx, "Plot High Low");

<static> displaySeriesAsLine(stx, sd, quotes)

Displays a single or group of series as lines in the study panel using CIQ.Studies.displayIndividualSeriesAsLine

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

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

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

sd studyDescriptor

The study descriptor. See CIQ.Studies.displayIndividualSeriesAsLine for accepted sd parameters.

quotes array

The set of quotes (dataSegment)

Example
var study = {
	overlay: true,
	yAxis: {},
	parameters: {
		plotType: "step",
	},
	seriesFN: function (stx, sd, quotes) {
		sd.extendToEnd = false;
		(sd.gaplines = false), CIQ.Studies.displaySeriesAsLine(stx, sd, quotes);
	},
};
CIQ.Studies.addStudy(stxx, "Vol", {}, { Volume: "green" }, null, null, study);

<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 CIQ.ChartEngine

The charting object

chart CIQ.ChartEngine.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> displayValuationLines(stx, sd)

Display "val lines" study.

It is possible to change how the lines appear with CSS styling. Example: .ciq-valuation-average-line { border-style: solid; border-width: 1.2px; opacity: 0.95; } .ciq-valuation-deviation-line { border-style: dotted; border-width: 1px; opacity: 0.80; }

These values are used to create the params argument for {CIQ.ChartEngine#plotLine}.

  • "border-style" -> "pattern"
  • "border-width" -> "lineWidth"
  • "opacity" -> "opacity"

Average line defaults to {pattern: 'solid', lineWidth: 1, opacity: 1} Deviation lines default to {pattern: 'dashed', lineWidth: 1, opacity: 1}

Suggested that whitespace be set from about 60 to 90 pixels so that the labels are clearly visible in the home position.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

sd studyDescriptor

The study descriptor

Examples
var stxx = new CIQ.ChartEngine({container: document.querySelector('.chartContainer'), preferences: {whitespace: 60.5}});

Alternatively, you can use yAxis labels by setting the labels parameter to "yaxis" in the studyLibrary entry.
CIQ.Studies.studyLibrary["val lines"].parameters = { labels: "yaxis" };

<static> displayVolumeProfile()

Creates a volume profile underlay for the chart. The underlay is always 25% of the width of the chart. The color is determined by the 'sd.outputs["Bars Color"]' parameter and opacity and border colors can be controlled with the class stx_volume_profile NOTE: Volume Profile will only display on the chart panel sharing the yAxis.


<static> doPostDrawYAxis(stx, yAxis)

studyOverZones will be displayed and Peaks & Valleys will be filled if corresponding thresholds are set in the study library as follows:

"parameters": {
	init:{studyOverZonesEnabled:true, studyOverBoughtValue:80, studyOverBoughtColor:"auto", studyOverSoldValue:20, studyOverSoldColor:"auto"}
}

Invoked by CIQ.ChartEngine.renderYAxis after createYAxis

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

yAxis CIQ.ChartEngine.YAxis

The axis to draw upon

Since:
  • 5.2.0


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

Draws a horizontal line on the study.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

sd studyDescriptor

The study descriptor

quotes array

The array of quotes (unused)

price number

The price (value) to draw the horizontal line

yAxis CIQ.ChartEngine.YAxis

The axis to use when drawing the line

color object

Optional color to use when drawing line. Can be a string or an object like {color:#334455, opacity:0.5}

Since:
  • 5.2.0 Added yAxis and color parameters.


<static> drawZones(stx, sd, quotes)

Plots over/under zones for indicators that support them, and when the user selects them.

This method will draw its own yAxis which will not have a scale, but merely the over under points.
Shading will be performed between the zone lines and the study plot.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

sd studyDescriptor

The study descriptor

quotes array

unused


<static> fetchAdditionalInstruments(stx, sd, syms [, params])

Ensures that symbols required by a study are loaded and maintained by the quotefeed.

Parameters:
Name Type Argument Description
stx CIQ.ChartEngine

The chart engine

sd object

The study descriptor

syms array

An array of 'symbol strings' or 'symbol objects' required by the study. If using symbol objets, in addition to our desired identifier elements, you must always include the symbol element in it (ie: symbolObject[i]={ symbol : mySymbol , otherStuff1 : xx , moreStuff : yy}.

params object <optional>

Parameters to be sent to addSeries. See CIQ.ChartEngine#addSeries.

Since:
  • 3.0.7 This was a previously private function.


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

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 CIQ.ChartEngine

A chart engine instance

studyName string

Type of study

inputs object

The inputs for this study instance

replaceID string <optional>

If it matches then return the same id

customName string <optional>

If this is supplied, use it to form the full study name. Otherwise studyName will be used.
ie: if custom name is 'SAMPLE', the unique name returned would resemble "SAMPLE(paam1,param2,param3,...)-X".

Since:
  • 5.1.1 Added customName argument; if supplied, use it to form the full study name. Otherwise studyName will be used.

Returns:

A unique name for the study

Type
string

<static> getFieldInputs(sd)

Returns an array of input field names which are used to specify the field for the study.

In most cases, this field is called "Field", but it does not have to be, nor does there need to be only one.

Parameters:
Name Type Description
sd studyDescriptor

The study descriptor

Since:
  • 3.0.0

Returns:

Input fields used to specify the field

Type
array

<static> getMarketOffset(stx, localQuoteDate, isForex)

Gets the difference between the local browser time and the market time.

Parameters:
Name Type Description
stx CIQ.ChartEngine

A reference to the chart object.

localQuoteDate object

A Date object that contains the date and time of the local quote.

isForex boolean

Indicates whether the market is a Forex (foreign exchange) market.

Since:
  • 8.0.0

Returns:

The market date/time minus the local date/time in milliseconds.

Type
number

<static> getPanelFromFieldName(stx, sd)

Returns the panel which the study's Field input value references.

For example, a ma (Moving Average) study with a Field of Volume may return the Volume panel, since that is the panel where the Field input value may be found..

Parameters:
Name Type Description
stx CIQ.ChartEngine

The charting object

sd studyDescriptor

The study descriptor

Since:
  • 6.3.0

Returns:

Name of panel containing the output field corresponding to the Field input value, null if not found

Type
string

<static> getStudyList(excludeList)

Function to determine which studies are available.

Parameters:
Name Type Description
excludeList object

Exclusion list of studies in object form ( e.g. {"rsi":true,"macd":true})

Since:
  • 3.0.0

Returns:

Map of available entries from CIQ.Studies.studyLibrary.

Type
object

<static> getYAxisParameters(stx, yAxis)

Retrieves parameters to be used to draw the Y Axis, retrieved from the study library.

If a range is set in the study library, the yAxis high and low properties are set.
Invoked by CIQ.ChartEngine.renderYAxis before createYAxis

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

yAxis CIQ.ChartEngine.YAxis

The axis to act upon

Since:
  • 5.2.0

Returns:

y-axis parameters such as noDraw, range, and ground

Type
object

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

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 CIQ.ChartEngine

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>

Additional parameters if required or supported by this study

panelName string <optional>

Deprecated. Panel name. Use parameters.panelName instead.

study object <optional>

Study definition to use in lieu of the study library entry

Since:
  • 3.0.0 Added study parameter.

Deprecated:
  • Since 6.3.0 panelName argument is deprecated; use parameters.panelName instead. If neither are valid, will automatically determine default panel.

Returns:

The newly initialized study descriptor

Type
studyDescriptor

<static> initPriceRelative(stx, type, inputs, outputs, parameters, panel)

Initializes data for Price Relative Study by fetching the comparing symbol.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

type string

Study type

inputs object

Study inputs

outputs object

Study outputs

parameters object

Study parameters

panel string

ID of the study's panel element

Since:
  • 09-2016-19

Returns:

Study descriptor object

Type
studyDescriptor

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

Moving Average convenience function.

Parameters:
Name Type Description
type string

The type of moving average, e.g. simple, exponential, triangular, etc. Valid options can be seen by inspecting the keys on the CIQ.Studies.movingAverage.typeMap object.

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, sending 'Signal' on a 'macd' study will result in an output field called "Signal ‌macd‌ (12,26,9)"

stx CIQ.ChartEngine

Chart object

sd object

Study Descriptor

subField string

Subfield within field to perform moving average on, if applicable. For example, IBM.Close: field:"IBM", subField:"Close"

Since:
  • 04-2015


<static> movingAverageHelper(stx, input)

Does conversions for valid moving average types

Parameters:
Name Type Description
stx CIQ.ChartEngine

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> overZones()

Deprecated:

<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()

Deprecated:
  • Yes

<static> removeStudy(stx, sd)

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

Parameters:
Name Type Description
stx CIQ.ChartEngine

A chart object

sd studyDescriptor

A study descriptor returned from CIQ.Studies.addStudy


<static> removeStudySymbols(sd, stx)

Removes any series that the study is referencing.

Parameters:
Name Type Description
sd object

Study descriptor.

stx CIQ.ChartEngine

The chart engine.

Since:
  • 3.0.0
  • 3.0.7 Changed name argument to take a study descriptor.
  • 3.0.7 Added required stx argument.

<static> replaceStudy(stx, id, type [, inputs] [, outputs] [, parameters] [, panelName] [, study])

Replaces an existing study with new inputs, outputs and parameters.

When using this method a study's position in the stack will remain the same. Derived (child) studies will shift to use the new study as well

Parameters:
Name Type Argument Description
stx CIQ.ChartEngine

The chart object

id string

The id of the current study. If set, then the old study will be replaced

type string

The name of the study (out of the studyLibrary)

inputs object <optional>

Inputs for the study instance. Default is those defined in the studyLibrary.

outputs object <optional>

Outputs for the study instance. Default is those defined in the studyLibrary.

parameters object <optional>

additional custom parameters for this study if supported or required by that study

panelName string <optional>

Optionally specify the panel. If not specified then an attempt will be made to locate a panel based on the input id or otherwise created if required.

study object <optional>

Optionally supply a study definition, overriding what may be found in the study library

Since:
  • 3.0.0 Added study parameter.

Returns:

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

Type
object

<static> smartCreateYAxis(stx, panel, name [, newPosition] [, defaultAxis])

Manages yAxis for a study when a new position is requested.

Parameters:
Name Type Argument Description
stx CIQ.ChartEngine

A chart engine instance

panel CIQ.ChartEngine.Panel

The panel where the yAxis is

name string

The study whose axis to manage

newPosition string <optional>

New position (left/right/none,default/shared, or specific axis name)

defaultAxis object <optional>

Axis defaults to use when creating new axis

Since:
  • 7.1.0

Returns:

The yAxis to use

Type
CIQ.ChartEngine.YAxis

<static> smartMovePanel(stx, inputs, panelName, replaceID, toNewPanel)

Manages the panel for a study when a new panel is requested.

Parameters:
Name Type Description
stx CIQ.ChartEngine

A chart engine instance.

inputs object

The study inputs.

panelName string

Name of the panel where the study will lie. Note: This panel's name may be changed in this function.

replaceID string

Name of the original study.

toNewPanel boolean

true if request to move to a new panel.

Since:
  • 7.1.0
  • 7.2.0 Added the toNewPanel argument.
Returns:

The panel to which the study was moved; null if a new panel needs to be created.

Type
CIQ.ChartEngine.Panel

<static> validateProjectedVolumeLookback(stx, sd)

Determines whether a projected volume lookback is valid for the currently selected periodicity.

Called by CIQ.Studies.calculateProjectedVolume.

Due to the data requirements of the Projected Volume at Time (PVAT) and Projected Aggregate Volume (PVA) studies, it is necessary to limit the maximum lookback.

Setting the lookback too high results in the chart attempting to load more data than is allowed by CIQ.ChartEngine#maxDataSetSize, which breaks the study. If you have set maxDataSetSize higher than the default, you may wish to replace this validation function with one that allows a greater lookback.

Parameters:
Name Type Description
stx CIQ.ChartEngine

A reference to the chart object.

sd studyDescriptor

Specifies the study (PVAT or PAV) for which the lookback is validated.

Since:
  • 8.0.0

Returns:

True if the the lookback is valid; otherwise, false.

Type
boolean

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

Deprecated since 6.0.0. Use CIQ.ChartEngine#drawHistogram instead.

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 CIQ.ChartEngine

The chart object

sd studyDescriptor

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.

Deprecated:
Example
var colorMap = {};
colorMap["#FF0000"] = [56, 123, null, null, 45];
colorMap["#00FF00"] = [null, null, 12, 13, null];

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

<static> volUnderlay(stx, sd, quotes)

Deprecated. Use CIQ.Studies.createVolumeChart instead.

Creates a volume underlay for the chart.

The underlay height is a % of the chart height as determined by yAxis.heightFactor.
Each bar width will be determined by WidthFactor study parameter.

Parameters:
Name Type Description
stx CIQ.ChartEngine

A chart engine instance

sd studyDescriptor

A study descriptor

quotes array

Array of quotes

Deprecated: