API Reference
Namespaces
Classes
Events
Global
Externals

Class: YAxis

CIQ.ChartEngine. YAxis


new YAxis(init)

Defines an object used for rendering the y-axis on a panel.

Each panel object will automatically include a y-axis object, which can be adjusted immediately after declaring your new CIQ.ChartEngine();
Any adjustments to the y-axis members after it has been rendered will require a draw() call to apply the changes. A call to initializeChart() may be required as well, depending on the setting being changed. See examples.

Also see:

For full customization instructions see:

Example: stxx.panels['chart'].yAxis

Example: stxx.chart.yAxis (convenience shortcut for accessing the main panel object - same as above)

Example: stxx.panels['Aroon (14)'].yAxis

Note: When modifying a y-axis placement setting (width, margins, position left/right, etc.) after the axis has been rendered, you must call CIQ.ChartEngine#calculateYAxisMargins or CIQ.ChartEngine#calculateYAxisPositions (as appropriate) followed by CIQ.ChartEngine#draw to activate the change.

Parameters:
Name Type Description
init object

Object containing custom values for y-axis members

Since:
  • 5.1.0 Created a name member which is used to determine if the y-axis is the same as another.

Examples
// here is an example on how to override the default top and bottom margins after the initial axis has already been rendered
stxx.loadChart(symbol, {masterData: yourData}, function () {
	// callback - your code to be executed after the chart is loaded
	stxx.chart.yAxis.initialMarginTop=50;
	stxx.chart.yAxis.initialMarginBottom=50;
	stxx.calculateYAxisMargins(stxx.chart.panel.yAxis); // must recalculate the margins after they are changed.
	stxx.draw();
});
// here is an example on how to override the default top and bottom margins before the initial axis has been rendered
var stxx=new CIQ.ChartEngine({container:document.querySelector(".chartContainer"), layout:{"candleWidth": 16, "crosshair":true}});
stxx.setPeriodicity({period:1, interval:1, timeUnit:"minute"}); 			// set your default periodicity to match your data. In this case one minute.
stxx.chart.yAxis.initialMarginTop=50;		// set default margins so they do not bump on to the legend
stxx.chart.yAxis.initialMarginBottom=50;
stxx.loadChart("SPY", {masterData: yourData});
// here is an example on how to turn off the last price label (main chart panel) before the initial axis has already been rendered
var stxx=new CIQ.ChartEngine({container:document.querySelector(".chartContainer"), layout:{"candleWidth": 16, "crosshair":true}});
stxx.chart.panel.yAxis.drawCurrentPriceLabel=false;

Members


allowSharing :boolean

Type:
  • boolean

allowZoom :boolean

If false then zoom interactions are disable on the yaxis

Type:
  • boolean
Since:
  • 9.1.0

Default Value:
  • true

bottom :number

Type:
  • number

bottomOffset :number

Sets the y-axis bottom on any panel. Rendering will start this number of pixels above the panel's bottom. Note that CIQ.ChartEngine#adjustPanelPositions and CIQ.ChartEngine#draw will need to be called to immediately activate this setting after the axis has already been drawn.

Visual Reference:
yAxis.width yAxis.width

Type:
  • number
Example
// The list of current panels can be found in "stxx.panels".
stxx.panels[panelName].yAxis.bottomOffset=20;
stxx.panels[panelName].yAxis.topOffset=60;
stxx.adjustPanelPositions();	// !!!! must recalculate the margins after they are changed. !!!!
stxx.draw();

decimalPlaces :number

Controls the number of decimal places on the y-axis labels.

Set to the preferred number of decimal places from 0 to 10, or leave null and the chart will choose automatically based on CIQ.ChartEngine.YAxis#shadowBreaks

Each y-axis will make its own determination, so to override this value for all axes, you must adjust the y-axis prototype.
Example: CIQ.ChartEngine.YAxis.prototype.decimalPlaces=4;

Note: study panel axis may be condensed using CIQ.condenseInt. See CIQ.ChartEngine#formatYAxisPrice for all details.

Type:
  • number
Since:
  • 5.2.0 Default changed to null.


displayBorder :boolean

Set to true to draw tick marks and a vertical border line at the edge of the y-axis (use with CIQ.ChartEngine.Chart#yaxisPaddingRight and CIQ.ChartEngine.Chart#yaxisPaddingLeft)

Type:
  • boolean
Default Value:
  • true

displayGridLines :boolean

Set to false to hide grid lines. See Gridlines and axis labels for additional details.

Type:
  • boolean
Default Value:
  • true
Examples

On a specific panel:

// Be sure to get the panel name directly from the panels object as it may contain ZWNJ characters.
// See http://documentation.chartiq.com/CIQ.ChartEngine.html#layout%5B%60panels%60%5D
stxx.layout.panels[panel_name_here].yAxis.displayGridLines=false;

On the primary chart panel:

stxx.chart.yAxis.displayGridLines=false;

drawCurrentPriceLabel :boolean

Set to false to hide the current price label in the main panel's y-axis.

Please note that the main panel's current price label will only display if there is a current price available. If you have not loaded enough datapoints to overlap into the current time, as determined by the device's clock, the label will not display.

The y-axis floating label colors are based on the difference between the most current close and the previous datapoint close, not the difference between the current datapoint's open and its close.

See CIQ.ChartEngine.AdvancedInjectable#drawCurrentHR

Visual Reference:
yAxis.drawCurrentPriceLabel

Type:
  • boolean
Since:
  • 04-2015

Default Value:
  • true

drawPriceLabels :boolean

Set to false to hide all price labels on the particular y-axis.
See CIQ.ChartEngine.YAxis#drawCurrentPriceLabel to disable just the current price label on the main chart panel.
See CIQ.ChartEngine.preferences.labels to disable just the last value label on studies.

Type:
  • boolean
Since:
  • 04-2015

Default Value:
  • true

drawSeriesPriceLabels :boolean

Set to false to hide the series price labels in the main panel's y-axis.

Type:
  • boolean
Since:
  • 3.0.0

Default Value:
  • true

flipped :boolean

Setting to true causes the y-axis and all linked drawings, series and studies to display inverted (flipped) from its previous state.

Type:
  • boolean
Since:
  • 6.3.0


fractional :object

Set to specify that the y-axis vertical grid be drawn with fractional intervals.

This is checked in CIQ.ChartEngine.AdvancedInjectable#drawYAxis and if it is not null, and there is no existing yAxis.priceFormatter, one is created to specially format the y-axis ticks.

CIQ.ChartEngine.YAxis#decimalPlaces and CIQ.ChartEngine.YAxis#maxDecimalPlaces will not be honored in this mode.

To disable the formatting, you must reset both the yAxis.priceFormatter and this fractional object to 'null'.
Example:

stxx.chart.yAxis.priceFormatter=stxx.chart.yAxis.fractional=null;

If the outlined logic is not suitable for your needs, you will need to create your own yAxis.priceFormatter

Type:
  • object
Examples

Usage example:

// Declare a CIQ.ChartEngine object. This is the main object for drawing charts
var stxx=new CIQ.ChartEngine({container:document.querySelector(".chartContainer"), layout:{"candleWidth": 16, "crosshair":true}});
// set axis to display in 1/32nds; for example, 100 5/32 will display as 100'05.  If there is a price midway between
// two ticks (for example, 11/64), a plus (+) will follow the price; for example 100 11/64 will display as 100'11+.
stxx.chart.yAxis.fractional={
		formatter: "'",				// This is the character used to separate he whole number portion from the numerator (' default)
		resolution: 1/32			// Set to smallest increment for the quoted amounts
}

 

Code used to perform the fractional formatting:

if(!yAxis.fractional.resolution) yAxis.fractional.resolution=yAxis.minimumPrice;
	if(!yAxis.fractional.formatter) yAxis.fractional.formatter="'";
	if(!yAxis.priceFormatter) yAxis.priceFormatter=function(stx, panel, price){
		if( !yAxis.fractional ) return;
		var sign='';
		if( price < 0 ) {
			sign="-";
			price= Math.abs(price);
		}
		var whole=Math.floor(Math.round(price/yAxis.fractional.resolution)*yAxis.fractional.resolution);
		var frac=Math.round((price-whole)/yAxis.fractional.resolution);
		var _nds=Math.floor(frac);
		return sign+whole+yAxis.fractional.formatter+(_nds<10?"0":"")+_nds+(frac-_nds>=0.5?"+":"");
	};

goldenRatioYAxis :boolean

When true, will attempt to create grid lines that approximate a golden ratio between x and y-axis by basing grid on CIQ.ChartEngine.YAxis#idealTickSizePixels. This creates an "airy" modern looking chart. If set to false, each axis will be adjusted separately and may create long and narrow rectangular grids depending on date or price range.

Type:
  • boolean
Since:
  • 04-2015
  • 4.0.0 Now defaults to true.
Default Value:
  • true

height :number

Type:
  • number

heightFactor :number

Factor that scales the y-axis.

The zoom value is internally adjusted based on the value of this property as follows:

zoom = (1 - heightFactor) * height + initial margin settings

For example, to reduce the scale of the y-axis by 20%, set heightFactor = 0.8.

Type:
  • number
Since:
  • 7.0.0

Default Value:
  • 1

high :number

Type:
  • number

highValue :number

Type:
  • number

highlight :boolean

Type:
  • boolean

idealTickSizePixels :number

Ideal size between y-axis values in pixels. Leave null to automatically calculate. See Gridlines and axis labels for additional details.

Note: If CIQ.ChartEngine.YAxis#goldenRatioYAxis is true, it will override idealTickSizePixels.

Type:
  • number

increments :array

Values used by the CIQ.ChartEngine.YAxis#pretty algorithm to set axis label locations. Note that overriding y-axis increments values works best when goldenRatioYAxis is set to false.

Type:
  • array
Since:
  • 2015-11-1

Default Value:
  • [1,2.5,5]
Example
stxx.chart.yAxis.goldenRatioYAxis=false;
stxx.chart.panel.yAxis.idealTickSizePixels=40;
stxx.chart.yAxis.increments=[2.5,5.2,40.8];

initialMarginBottom :number

Set this to automatically compress and offset the y-axis so that these many pixels of white space are below the display. Note that CIQ.ChartEngine#calculateYAxisMargins and CIQ.ChartEngine#draw will need to be called to immediately activate this setting after the axis has already been drawn.

Visual Reference:
yAxis.width

Type:
  • number
Default Value:
  • 10
Examples
// Here is an example on how to override the default top and bottom margins before the initial axis has been rendered.
var stxx=new CIQ.ChartEngine({container:document.querySelector(".chartContainer"), layout:{"candleWidth": 16, "crosshair":true}});
stxx.setPeriodicity({period:1, interval:1, timeUnit:"minute"}); // Set your default periodicity to match your data; in this case, one minute.
stxx.chart.yAxis.initialMarginTop = 50; // Set default margins so they do not bump on to the legend.
stxx.chart.yAxis.initialMarginBottom = 50;
stxx.loadChart("SPY", {masterData: yourData});
// Here is an example on how to override the default top and bottom margins after the initial axis has already been rendered.
stxx.loadChart(symbol, {masterData: yourData}, function() {
	// Callback -- your code to be executed after the chart is loaded.
	stxx.chart.yAxis.initialMarginTop = 50;
	stxx.chart.yAxis.initialMarginBottom = 50;
	stxx.calculateYAxisMargins(stxx.chart.panel.yAxis); // !!!! Must recalculate the margins after they are changed. !!!!
	stxx.draw();
});

initialMarginTop :number

Set this to automatically compress and offset the y-axis so that these many pixels of white space are above the display. Note that CIQ.ChartEngine#calculateYAxisMargins and CIQ.ChartEngine#draw will need to be called to immediately activate this setting after the axis has already been drawn.

Visual Reference:
yAxis.width

Type:
  • number
Default Value:
  • 10
Examples
// Here is an example on how to override the default top and bottom margins before the initial axis has been rendered.
var stxx=new CIQ.ChartEngine({container:document.querySelector(".chartContainer"), layout:{"candleWidth": 16, "crosshair":true}});
stxx.setPeriodicity({period:1, interval:1, timeUnit:"minute"}); // Set your default periodicity to match your data; in this case, one minute.
stxx.chart.yAxis.initialMarginTop = 50; // Set default margins so they do not bump on to the legend.
stxx.chart.yAxis.initialMarginBottom = 50;
stxx.loadChart("SPY", {masterData: yourData});
// Here is an example on how to override the default top and bottom margins after the initial axis has already been rendered.
stxx.loadChart(symbol, {masterData: yourData}, function () {
	var yAxis = stxx.chart.yAxis;

	yAxis.initialMarginTop = 50;
	yAxis.initialMarginBottom = 50;

	// !! Must recalculate margins after they are changed!
	stxx.calculateYAxisMargins(yAxis);
	stxx.draw();
});
// Here is an example on how to override the default top and bottom margins for a specific panel after the initial axis has already been rendered.
// The list of current panels can be found in stxx.panels.
stxx.panels[panelName].yAxis.initialMarginTop = 100;
stxx.panels[panelName].yAxis.initialMarginBottom = 100;
stxx.calculateYAxisMargins(stxx.panels[panelName].yAxis); // !!!! Must recalculate the margins after they are changed. !!!!
stxx.draw();

justifyRight :boolean

Set to true to right justify the yaxis labels Set to false to force-left justify the labels, even when the axis is on the left. Set to null to have the justification automatically adjusted based on the axis position. Right axis will justify left, and left axis will justify right.

This setting does not control the floating last price. See CIQ.ChartEngine.AdvancedInjectable#drawCurrentHR and CIQ.ChartEngine#createYAxisLabel

Type:
  • boolean
Since:
  • 15-07-01
  • 6.2.0 Formalized distinction between null and false values.

left :number

Type:
  • number

logHigh :number

Type:
  • number

logLow :number

Type:
  • number

logShadow :number

Type:
  • number

low :number

Type:
  • number

lowValue :number

Type:
  • number

max :number

Optionally hard set the high (top value) of the yAxis (for instance when plotting 0 - 100% charts)

Type:
  • number

maxDecimalPlaces :number

Controls maximum number of decimal places to ever display on a y-axis floating price label.

Set to the maximum decimal places from 0 to 10, or leave null and the chart will choose automatically based on CIQ.ChartEngine.YAxis#shadowBreaks.

Type:
  • number
Since:
  • 5.2.1 Default changed to null.


min :number

Optionally hard set the low (bottom value) of the yAxis (for instance when plotting 0 - 100% charts)

Type:
  • number

minimumPriceTick :number

Set to specify that the y-axis vertical grid be drawn with specific intervals between ticks. This amount will be overridden if it will result in y-axis crowding. In which chase, multiples of the original interval will be used. For example, if .25 is selected, and that will cause labels to be on top of or too close to each other, .50 may be used. Crowding is prevented by allowing for a minimum of space equating the y-axis font height between labels.

This parameter is also used in the 'Trade From Chart' (TFC) module. If set, it will force the widget to skip certain price values and instead 'snap' to your desired intervals. This will guarantee that an order is only placed at the allowed price intervals for the security in question.

Note that this parameter will be ignored if CIQ.ChartEngine.YAxis#pretty is set to true. If you require specific price intervals, please set CIQ.ChartEngine.YAxis#pretty to 'false' before setting minimumPriceTick

Visual Reference:
yAxis.minimumPriceTick

Type:
  • number
Example
// Declare a CIQ.ChartEngine object. This is the main object for drawing charts
var stxx=new CIQ.ChartEngine({container:document.querySelector(".chartContainer"), layout:{"candleWidth": 16, "crosshair":true}});
// set interval between ticks
stxx.chart.yAxis.minimumPriceTick=.50;

multiplier :number

Type:
  • number

name :string

Type:
  • string

noDraw :boolean

Switch to 'temporarily' hide the y-axis. Set to `true' to activate. Will not modify the location of the axis; to do that use CIQ.ChartEngine#setYAxisPosition instead.

Type:
  • boolean

position :string

Set to "left" or "right" to initialize the y-axis location.

By default, y-axis are drawn on the right side of the chart. The main y-axis for any study panel will follow the main chart axis as long as this is set to null.

Do not use this method to change the location of an existing y-axis. Once initialized, y-axis location can be changed at any time by calling CIQ.ChartEngine#setYAxisPosition

Type:
  • string
Since:
  • 15-07-01

Examples

Pre-set the main y-axis for the chart on the left; **before it is initially rendered**.

stxx.chart.yAxis.position = 'left';

Re-set the main y-axis for the chart on the right; **after it is initially rendered**.

stxx.setYAxisPosition(stxx.chart.yAxis,'right');

pretty :boolean

If true then uses the "pretty" algorithm instead of the "best fit" algorithm. The pretty algorithm uses the values specified in CIQ.ChartEngine.YAxis#increments to set axis label locations.

Note that this algorithm will override the CIQ.ChartEngine.YAxis#minimumPriceTick. If you require specific price intervals, please set this parameter to 'false' before setting minimumPriceTick

Type:
  • boolean
Since:
  • 2015-11-1

Default Value:
  • true

prettySemiLog :boolean

If true then uses an additional step in the "pretty" algorithm for the log scale. This allows the algorithm to lower the grid to fill large visual gaps. The "increments" are not fully respected by this approach.

Only applicable when using both pretty mode and semiLog.

Type:
  • boolean
Since:
  • 2016-03-11

Default Value:
  • true

priceFormatter :function

Optional function used to override default formatting of y-axisvalues, including the floating HUD value of the crosshair.

Expected format :

	function(stx, panel, price, decimalPlaces)

Parameters:

	stx           - CIQ.ChartEngine       - The chart object
	panel         - CIQ.ChartEngine.Panel - The panel
	price         - number                - The price to format
	decimalPlaces - number                - Optional - Number of decimal places to use
												(may not always be present)

Returns:

	text - Formatted text label for the price
Type:
  • function
Example
stxx.chart.yAxis.priceFormatter=function(stx, panel, price, decimalPlaces){
	var convertedPrice;
	  // add our logic here to convert 'price' to 'convertedPrice'
   return convertedPrice; // string
}

priceTick :number

Type:
  • number

printDecimalPlaces :number

Type:
  • number

renderers :array

Type:
  • array

scroll :number

set this to the number of pixels to offset the y-axis, positive or negative.

Type:
  • number

semiLog :boolean

Type:
  • boolean

shadow :number

Type:
  • number

shadowBreaks :array

A matrix used to determine how many decimal places to print on y-axis labels based on the size of the shadow (the difference between chart high and chart low). The array consists of tuples in descending order. If the shadow is less than n1 then n2 decimal places will be printed. See CIQ.ChartEngine.YAxis.defaultShadowBreaks and CIQ.ChartEngine.YAxis.smallChartShadowBreaks for default settings.

This can be overridden, however, by settingCIQ.ChartEngine.YAxis#decimalPlaces. If you wish to further configure the current price label floating over the y-axis to display less decimal places than the axis labels, set CIQ.ChartEngine.YAxis#maxDecimalPlaces. Also see CIQ.ChartEngine.Chart#dynamicYAxis to allow the y-axis to automatically determine its width based on the text length of quotes in a dataSet.

Type:
  • array
Since:
  • 2015-11-1

Examples
stxx.chart.yAxis.shadowBreaks=CIQ.ChartEngine.YAxis.defaultShadowBreaks;
stxx.chart.yAxis.shadowBreaks=CIQ.ChartEngine.YAxis.smallChartShadowBreaks;

smallScreenWidth :number

The y-axis width in pixels if the screen is small (typically, smaller than the break-sm breakpoint). See the CIQ.ChartEngine.Chart#breakpoint property and CIQ.UI.Chart#getBreakpoint method for more information on breakpoints.

Type:
  • number
Since:
  • 8.2.0

Default Value:
  • 1

studies :array

Type:
  • array

textBackground :boolean

Set to true to put a rectangle behind the yaxis text (use with CIQ.ChartEngine.Chart#yaxisPaddingRight and CIQ.ChartEngine.Chart#yaxisPaddingLeft)

Type:
  • boolean
Since:
  • 15-07-01


textStyle :string

Override the default stx_yaxis style for text by setting this to the desired CSS style. This would typically be used to set a secondary-axis to a particular color.

Type:
  • string
Since:
  • 15-07-01


title :string|function|null

If set, will override the axis title (if enabled) Set to a function will receive chart engine, panel and y-axis as parameters to return the title string to display

Type:
  • string | function | null
Since:
  • 9.2.0


top :number

Type:
  • number

topOffset :number

Sets y-axis top on Study panels. Rendering will start this number of pixels below the panel's top. Note that CIQ.ChartEngine#adjustPanelPositions and CIQ.ChartEngine#draw will need to be called to immediately activate this setting after the axis has already been drawn.

Visual Reference:
yAxis.width

Type:
  • number
Example
// The list of current panels can be found in "stxx.panels".
stxx.panels[panelName].yAxis.bottomOffset=20;
stxx.panels[panelName].yAxis.topOffset=60;
stxx.adjustPanelPositions();	// !!!! must recalculate the margins after they are changed. !!!!
stxx.draw();

width :number

The y-axis width in pixels.

yAxis.width

Type:
  • number
Default Value:
  • 1
See:
Examples

Set the y-axis width.

stxx.chart.yAxis.width = stxx.chart.yAxis.smallScreenWidth;
// Must call the following two lines to activate the update if the axis is already drawn.
stxx.calculateYAxisPositions();
stxx.draw();

Reset the y-axis width to the default.

stxx.chart.yAxis.width = CIQ.ChartEngine.YAxis.prototype.width;
stxx.calculateYAxisPositions();
stxx.draw();

yAxisPlotter :CIQ.Plotter

Type:

yaxisLabelStyle :string

Shape of the floating y-axis label.

Available options:

It will default to CIQ.ChartEngine#yaxisLabelStyle. This could be set independently on each panel if desired.

Type:
  • string
Since:
  • 04-2015

Example
var stxx=new CIQ.ChartEngine({container:document.querySelector(".chartContainer"), layout:{"candleWidth": 16, "crosshair":true}});
stxx.chart.yAxis.yaxisLabelStyle="rect"

zoom :number

Sets the vertical zoom level for the y-axis and all its associated series.

It can be set programmatically or by the user as they grab the y-axis and move it up or down.

The value represents the number of pixels to zoomed in or out and can be positive or negative. The larger the number, the more it zooms out to show a wider price range.

Please note that the zoom level will be reset as determined by CIQ.ChartEngine.YAxis#initialMarginTop and CIQ.ChartEngine.YAxis#initialMarginBottom when a CIQ.ChartEngine#loadChart is rendered, the CIQ.ChartEngine#home button is pressed, or when CIQ.ChartEngine.AdvancedInjectable#touchDoubleClick is activated on a touch device.

Type:
  • number
Example
// programmatically change the vertical zoom level for the primary chart yAxis
stxx.chart.yAxis.zoom=100;stxx.draw();

defaultShadowBreaks :array

Default setting for the array that determines how many decimal places to print based on the size of the shadow (the difference between chart high and chart low). The array consists of tuples in descending order. If the shadow is less than n1 then n2 decimal places will be printed. See CIQ.ChartEngine.YAxis#shadowBreaks

Type:
  • array
Since:
  • 2015-11-1
  • 5.2.0 Additional break added.
Default Value:
  • ["[1000,2]","[5,4]","[0.001,8]"]

smallChartShadowBreaks :array

Alternative setting (for small charts) array that determines how many decimal places to print based on the size of the shadow (the difference between chart high and chart low). The array consists of tuples in descending order. If the shadow is less than n1 then n2 decimal places will be printed. See CIQ.ChartEngine.YAxis#shadowBreaks

Type:
  • array
Since:
  • 2015-11-1

Default Value:
  • ["[10,2]","[1,4]"]

Methods


isShared(stx, includeDependents)

Convenience function for checking whether multiple plots share this axis.

Parameters:
Name Type Description
stx CIQ.ChartEngine

A chart engine instance.

includeDependents boolean

Set to true to count dependent renderers among the plots sharing the axis.

Since:
  • 7.2.0
  • 7.3.0 Added stx and includeDependents parameters.

setBackground(stx [, params])

Sets the background of the axis when hovering over it to indicate more action are available, such as zooming and dragging.

To disable color change on hover, set to a stub function:

CIQ.ChartEngine.YAxis.prototype.setBackground=function(stx, params){};
Parameters:
Name Type Argument Description
stx CIQ.ChartEngine

A chart engine instance

params object <optional>
Properties
Name Type Argument Description
color string <optional>

background color

opacity number <optional>

opacity of background color

Since:
  • 7.1.0


setBreakpointWidth(breakpoint)

Sets the y-axis width based on the breakpoint parameter.

Parameters:
Name Type Description
breakpoint string

The responsive design breakpoint that determines the y-axis width. See the CIQ.UI.Chart#getBreakpoint method for valid values.

Since:
  • 8.2.0