Class: Outliers

CIQ. Outliers


new Outliers(params)

Creates the outliers add-on which scales the y-axis to the main trend, hiding outlier values. Markers are placed at the location of the outlier values enabling the user to restore the full extent of the y-axis by selecting the markers.

Requires js/addOns.js.

Chart with hidden outliers

Parameters:
Name Type Description
params object

Configuration parameters.

Properties
Name Type Argument Default Description
stx CIQ.ChartEngine <optional>

A reference to the chart object.

multiplier number <optional>
3

Sets the threshold for outliers by multiplying the normal data range. The default value hides only extreme outliers.

altColors Array <optional>

An array of hexadecimal color values used to style outlier markers when multiple y-axes share the same panel. Markers for the first additional y-axis are styled with the value at index 0; markers for the second additional y-axis, the value at index 1; and so forth. If not provided, a default array of colors is assigned.

menuContextClass string <optional>

A CSS class name used to query the menu DOM element that contains the UI control for the outliers add-on. In a multi-chart document, the add-on is available only on charts that have a menu DOM element with the value for menuContextClass as a class attribute.

Since:
  • 7.5.0
  • 8.0.0 Added params.altColors and params.menuContextClass.
Example
new CIQ.Outliers({ stx: stxx });

Methods


deprecateMarkers(targetAxis)

Removes all markers from targetAxis that are no longer fresh; that is, markers that do not represent data points in the current data set, or axis markers that are irrelevant because high or low outliers no longer exist. Sets the status of all remaining outlier markers to stale, or not fresh (the freshness status should subsequently be reevaluated).

Parameters:
Name Type Description
targetAxis object

The y-axis for which the markers are deprecated. Note: A chart or panel can have multiple y-axes; each y-axis has its own outlier markers based on the data rendered on the axis.

Since:
  • 7.5.0
  • 8.0.0 Added targetAxis parameter.

find(dataSet)

Finds the outliers contained in dataSet.

Note: This function may be overridden to provide a custom algorithm for finding outliers.

Parameters:
Name Type Description
dataSet Array

An array of objects of the form {value: Number, quote: Object}. Each object contains a value and its associated quote. The value is checked to determine whether it is an outlier of the data set. When checking more than one value for a quote (such as an OHLC quote), each value is included in a separate object; for example, [{value: open, quote: quote}, {value: high, quote: quote}, {value: low, quote: quote}, {value: close, quote: quote}...].

Since:
  • 7.5.0
  • 8.0.0 Added return value.
Returns:

An object of the form:

{
	// Minimum and maximum threshold values of dataSet to be considered an outlier.
	minValue: null,
	maxValue: null,
	// Mininum and maximum values of dataSet that are not considered outliers.
	// Will be the least and greatest values in dataSet if no outliers are found.
	trendMin: null,
	trendMax: null,
	// Minimum and maximum values of dataSet that are considered outliers.
	// Will remain null if no outliers are found.
	outlierMin: null,
	outlierMax: null,
	// Array of individual outlier information for marker placement, in the format {DT:DateTime, value:Number, position:String}
	// (position is either 'high' or 'low').
	activeOutliers: []
}
Type
object

flipMarkers(targetAxis)

Repositions outlier markers from the top of the display to the bottom (or vice versa) when the associated y-axis has been flipped (inverted).

Parameters:
Name Type Description
targetAxis object

The y-axis that has been flipped.

Since:
  • 8.0.0


handleMarkerClick(position, targetAxis, targetNode)

Calls setDisplayState in response to selecting an outlier marker.

Parameters:
Name Type Description
position string

The position of the marker; either "high" or "low".

targetAxis object

The y-axis that contains the selected marker. Note: Charts and panels can have multiple y-axes; each y-axis has its own outlier markers.

targetNode HTMLElement

The selected outlier marker DOM node.

Since:
  • 8.0.0


markAxis(position, targetAxis)

Places markers on the y-axis when high or low outliers exist.

Parameters:
Name Type Description
position string

The position of the marker; either "high" or "low". If the position is "high", the marker is placed at the top of the axis; if "low", at the bottom of the axis.

targetAxis object

The y-axis on which the markers are placed. Note: Charts and panels can have multiple y-axes, each with its own outlier markers.

Since:
  • 7.5.0
  • 8.0.0 Added position and targetAxis parameters and return value.
Returns:

The axis outlier marker, which is added to the display.

Type
CIQ.Marker

markOutlier(data, position, targetAxis)

Adds an outlier marker to a tick (data point).

Parameters:
Name Type Description
data object

Represents the tick that is marked as an outlier. Contains the outlier value and its associated quote; for example, {value: Number, quote: Object}.

position string

The position of the marker; either "high" or "low". If the position is "high", the marker is placed at the top of the chart; if "low", at the bottom of the chart.

targetAxis object

The y-axis to which the marker is added. Note: A chart or panel can have multiple y-axes; each y-axis has its own outlier markers.

Since:
  • 7.5.0
  • 8.0.0 Added targetAxis parameter.
Returns:

The outlier marker, which is added to the display.

Type
CIQ.Marker

matchYAxisStyle(node)

Sets the CSS style properties of the y-axis outlier marker to match the CSS styling of the y-axis itself.

Parameters:
Name Type Description
node HTMLElement

The y-axis marker to style.

Since:
  • 7.5.0


processDataSet(dataSet, panel, axis)

Checks for outlier values in dataSet, and adds outlier markers (data point markers and axis markers) to axis.

Parameters:
Name Type Description
dataSet Array

An array of objects of the form {value: Number, quote: Object}. Each object contains a value and its associated quote. The value is checked to determine whether it is an outlier of the data set. When checking more than one value for a quote (such as an OHLC quote), each value is included in a separate object; for example, [{value: open, quote: quote}, {value: high, quote: quote}, {value: low, quote: quote}, {value: close, quote: quote}...].

panel object

The panel where dataSet is rendered.

axis object

The y-axis against which dataSet is rendered. Note: Charts and panels can have multiple y-axes; each y-axis has its own set of outlier markers based on the data rendered on the axis.

Since:
  • 8.0.0

Returns:

A tuple consisting of the outlier minimum and maximum — or trend minimum and maximum, if no outliers are found — to be handled by the CIQ.ChartEngine#determineMinMax method. See the return value of the find function for a description of outlier and trend minimum and maximum.

Type
Array

refreshAxisMarkers(node, targetAxis)

Updates the position of the axis outlier marker represented by node.

Parameters:
Name Type Description
node HTMLElement

The axis marker to position.

targetAxis object

The y-axis on which the axis marker is positioned.

Since:
  • 7.5.0
  • 8.0.0 Added targetAxis parameter.

refreshMarkerArray(targetAxis)

Updates the freshness status of outlier markers belonging to targetAxis.

Sets the status to fresh if the markers represent data points in the activeOutliers list of targetAxis or a marker is an axis marker for high or low outliers and high or low outliers exist. (See the return value of the find function for a description of the activeOutliers list.)

Adds new markers to targetAxis for data points in the activeOutliers list not already represented by a marker (see markOutlier). Adds new axis markers if the data set rendered on targetAxis contains high or low outliers and the respective axis marker does not exist (see markAxis).

Sets the status of all other markers belonging to targetAxis to stale, or unfresh (these markers are ultimately removed).

Parameters:
Name Type Description
targetAxis object

The y-axis for which the markers are refreshed. Note: Charts and panels can have multiple y-axes, each with its own array of outlier markers.

Since:
  • 8.0.0


refreshMarkers(targetAxis)

Updates the display styles of all outlier markers belonging to targetAxis, including data point markers and axis markers. Shows the markers if outliers are hidden and the marked outliers exceed the bounds of targetAxis. Flips the markers if targetAxis has been inverted (see flipMarkers).

Parameters:
Name Type Description
targetAxis object

The y-axis on which the markers are refreshed. Note: Charts and panels can have multiple y-axes, each with its own outlier markers.

Since:
  • 8.0.0


removeAllMarkers(targetAxis)

Removes all outlier markers from targetAxis, including data point markers and y-axis markers.

Parameters:
Name Type Description
targetAxis object

The y-axis from which the markers are removed. Note: Charts and panels can have multiple y-axes, each with its own outlier markers.

Since:
  • 7.5.0
  • 8.0.0 Added targetAxis parameter.

setDisplayState(newState, targetAxis)

Sets the outlier display state, which determines whether to display outlier markers.

Parameters:
Name Type Description
newState string

The intended display state; should be one of:

  • "high" — Show high outliers; hide high outlier markers.
  • "low" — Show low outliers; hide low outlier markers.
  • "all" — Show high and low outliers; hide high and low outlier markers.
  • "none" — Hide high and low outliers; show high and low outlier markers.
If none of the above is provided, "none" is assumed.
targetAxis object

The y-axis on which the outlier state is set. Note: A chart or panel can have multiple y-axes.

Since:
  • 7.5.0
  • 8.0.0 Added targetAxis parameter.

setMarkerColor(node, color)

Applies a background color to an outlier data point marker.

Parameters:
Name Type Description
node HTMLElement

The outlier marker DOM node to which the background color is applied.

color string

The hexadecimal color value set as the node background color.

Since:
  • 8.0.0


updateMarkerVisibility()

Shows or hides outlier markers based on the display state.

See setDisplayState.

Since:
  • 7.5.0