API Reference
Namespaces
Classes
Events
Global
Externals

Class: Histogram

CIQ.Renderer. Histogram

Creates a multi-part histogram renderer where bars can be stacked one on top of the other, clustered next to each other, or overlaid over each other.

Important Considerations:

  • If you are customizing your Histogram to include a baseline, it is recommended that you render it on a separate panel, especially if your primary series' renderer includes its own baseline. This is because histograms require their own Y-Axis to render a baseline. The end result would include two distinct baselines, which might lead to confusion in data interpretation.
  • While "stacked" histograms can be used with a combination of positive and negative values or with a baseline, the results are not optimal. Therefore, we do not recommend using these combinations, as they are not fully supported.

If you want to display multiple series with baselines on the main chart, refer to this example which demonstrates how to synchronize two distinct baselines.
Note: This advanced configuration is not included with ChartIQ and requires development on your end.

new Histogram(config)

See CIQ.Renderer#construct for parameters required by all renderers.

See CIQ.ChartEngine#drawHistogram for more details.

Parameters:
Name Type Description
config Object

Config for renderer

Properties
Name Type Argument Description
params object <optional>

Parameters to control the renderer itself

Properties
Name Type Argument Default Description
defaultBorders boolean <optional>
 false

Whether to draw a border for each bar as a whole. Can be overridden by a border set for a series.
widthFactor number <optional>
 .8

Width of each bar as a percentage of the candleWidth. Valid values are 0.00-1.00.
colMargin number <optional>

Space between columns in the cluster. Larger or equal to 1 defines pixel width between clustered columns, if less than 1 - percentage of the cluster width.
heightPercentage number <optional>
 .7

The amount of vertical space to use, valid values are 0.00-1.00.
bindToYAxis boolean <optional>
 true

Set to true to bind the rendering to the y-axis and to draw it. Automatically set if params.yAxis is present.
subtype string <optional>
 "overlaid"

Subtype of rendering "stacked", "clustered", "overlaid"
priority number <optional>

Priority in the list of renderer layering order within over or under chart grouping. Renderers with higher priority will be layered first. The parameter allows to render histograms with larger areas behind renderers with smaller areas. It is applicable to all renderers.
errorMessage string | null <optional>

Error message override for when there is no data to render in the visible chart area. Set to null to never display error message.

Common valid parameters for use by attachSeries.:
fill_color_up - Color for histogram bars when the Close is higher than the previous Close.
fill_color_down - Color for histogram bars when the Close is lower than the previous Close.
border_color_up - Border color for histogram bars when the Close is higher than the previous Close.
border_color_down - Border color for histogram bars when the Close is lower than the previous Close.

See CIQ.Renderer#attachSeries for additional parameters.
Version:
  • ChartIQ Advanced Package
Since:
  • 7.5.0 Added the ability to draw negative bars when yAxis.baseline is set to zero or some other value (see examples).
  • 9.6.0 Added config.params.priority and config.params.colMargin parameter
  • 9.7.0 Added config.params.errorMessage parameter.
Examples
// configure the histogram display
const params={
    name: "Sentiment Data",
    subtype: "stacked",
    heightPercentage: 0.7,	 // how high to go. 1 = 100%
    widthFactor: 0.8	 // to control space between bars. 1 = no space in between
};

//legend creation callback (optional)
function histogramLegend(colors){
    stxx.chart.legendRenderer(stxx,{legendColorMap:colors, coordinates:{x:260, y:stxx.panels["chart"].yAxis.top+30}, noBase:true});
}

// set the renderer
const histRenderer=stxx.setSeriesRenderer(new CIQ.Renderer.Histogram({params: params, callback: histogramLegend}));

// add data and attach.
stxx.addSeries("^NIOALL", {display:"Symbol 1"}, function() {histRenderer.attachSeries("^NIOALL","#6B9CF7").ready();});
stxx.addSeries("^NIOAFN", {display:"Symbol 2"}, function() {histRenderer.attachSeries("^NIOAFN","#95B7F6").ready();});
stxx.addSeries("^NIOAMD", {display:"Symbol 3"}, function() {histRenderer.attachSeries("^NIOAMD","#B9D0F5").ready();});
// this is an example on how to completely remove a renderer and all associated data.
// This should only be necessary if you are also removing the chart itself

// Remove all series from the renderer including series data from the masterData
renderer.removeAllSeries(true);

// detach the series renderer from the chart.
stxx.removeSeriesRenderer(renderer);

// delete the renderer itself.
delete renderer;

Create a histogram renderer on a separate panel with a baseline value, allowing negative bars.

const yax = new CIQ.ChartEngine.YAxis({
    position: "left",
    baseline: { value: 105 }
});

// Optionally create a separate panel to prevent baseline conflicts with the main chart.
stxx.createPanel("Histogram Panel", "histogram", null, null);

const histRenderer = stxx.setSeriesRenderer(
    new CIQ.Renderer.Histogram({
        params: {
            subtype: 'clustered',
            panel: "histogram", // Use the previously created panel.
            yAxis: yax,
        }
    })
);

stxx.addSeries("AMZN", null, function () { histRenderer.attachSeries("AMZN", { color: 'blue' }).ready(); });
stxx.addSeries("MSFT", null, function () { histRenderer.attachSeries("MSFT", { color: 'white' }).ready(); });
stxx.addSeries("GOOGL", null, function () { histRenderer.attachSeries("GOOGL", { color: 'orange' }).ready(); });

Render a horizontal line at the baseline value.

const yAxis = new CIQ.ChartEngine.YAxis({
    position: "left",
    baseline: {
        value: 100,
        // Must provide color to render the horizontal line,
        // and can optionally provide pattern, lineWidth, and opacity.
        color: "red",
        pattern: "dotted",
        lineWidth: 2,
        opacity: 1
    }
});
stxx.addSeries("GOOG", {
    renderer: "Histogram",
    color: "steelblue",
    // baseline: { defaultLevel: 100 }, // Add this property to vertically center the baseline at the `defaultLevel` value of 100.
    yAxis
});

Extends

Members

init :object

You may set any initial parameters of the renderer here, and they will be used as default values in the renderer's params object. In order for these init values to take effect, they must be set on the prototype before the renderer is produced. This object is useful when you do not have access to the constructor, like when using stxx.setChartType.

Type:
  • object
Since:

  • 8.4.0

Inherited From:
Overrides:
Default Value:
  • {}
Example
// Turns on heads-up display mode for the market depth chart.
CIQ.Renderer.prototype.init = { headsUp: true };
stxx.setChartType("marketdepth_mountain_volume");

Methods

adjustYAxis()

If your renderer manages a y-axis then the necessary adjustments to its properties should be made here.

Since:

  • 5.2.0

Inherited From:
Overrides:

attachSeries(id, parameters)

Attach a series to the renderer.

This assumes that the series data is already in the dataSet and simply connects it to the renderer with the specified parameters. See CIQ.ChartEngine#addSeries for details on how to create a series.

Any parameters defined when attaching a series, such as colors, will supersede any defined when a series was created. This allows you to attach the same series to multiple renderers, each rendering displaying the same series data in a different color, for example.

Parameters:
Name Type Description
id string

The name of the series.
parameters object | string

Settings to control color and opacity of each series in the group. See CIQ.ChartEngine#addSeries for implementation examples.

Argument format can be:

  • a string containing the color
  • or a more granular object having the following members:

Properties
Name Type Argument Default Description
field string <optional>

The name of the field. Name of the field in the dataSet to use for the series. If omitted, defaults to id
fill_color_up string <optional>

Color to use to fill the part when the Close is higher than the previous (or 'transparent' to not display)
border_color_up string <optional>

Color to use to draw the border when the Close is higher than the previous (or 'transparent' to not display)
opacity_up number <optional>
 .4

Opacity to use to fill the part when the Close is higher than the previous (0.0-1.0)
border_color_even string <optional>

Color to use to draw the border when the Close is equal to the previous (or 'transparent' to not display)
fill_color_down string <optional>

Color to use to fill the part when the Close is lower than the previous (or 'transparent' to not display)
border_color_down string <optional>

Color to use to draw the border when the Close is lower than the previous (or 'transparent' to not display)
opacity_down number <optional>
 .4

Opacity to use to fill the part when the Close is lower than the previous (0.0-1.0)
color string <optional>

Color to use to fill the series in the absence of specific up/down color.
border_color string <optional>

Color to use to draw the border in the series in the absence of specific up/down color.
fillStyle string <optional>

Color to use to fill the mountain chart.
baseColor string <optional>

Color to use at the bottom of the mountain chart, will create a gradient with bgColor
bgColor string <optional>

Color to use at the top of the mountain chart, will create a gradient if baseColor is specified. Otherwise, will fill the mountain solid with this color unless fillStyle is specified
permanent boolean <optional>

Whether the attached series can be removed by the user (lines and bars only). By default, the series will not be permanent. This flag (including the default) will supersede the permanent flag of the actual series. As such, a series will not be permanent unless you set this flag to 'true', even if the series being attached was flaged set as permanent when defined. This gives the renderer most control over the rendering process.
labels object <optional>

Draw labels when set for histogram and line renderers

Properties
Name Type Argument Default Description
backgroundColor string <optional>

Label background color override
textColor string <optional>

Label text color override
font string <optional>
 "12px Arial"

Label font override
bold boolean <optional>

Whether the font should be bold
italic boolean <optional>

Whether the font should be italic
padding number <optional>

Label padding override
verticalOffset number <optional>

Label vertical offset override
insideBar boolean <optional>

Whether to draw labels inside histogram bars
lastVisibleOnly boolean <optional>

Draw only the last visible label
Since:

  • 5.1.0 Added fillStyle, baseColor, and bgColor parameters.

    • 9.6.0 Added parameters.priority and parameters.labels object with backgroundColor, textColor, font, bold, italic, padding, verticalOffset, insideBar and lastVisibleOnly properties
Inherited From:
Overrides:
Returns:

Returns a copy of this for chaining

Type
CIQ.Renderer
Example
// add multiple series and attach to a custom y-axis on the left.

	// note how the addSeries callback is used to ensure the data is present before the series is displayed

	//create the custom axis
	var axis=new CIQ.ChartEngine.YAxis();
	axis.position="left";
	axis.textStyle="#FFBE00";
	axis.decimalPlaces=0;			// no decimal places on the axis labels
	axis.maxDecimalPlaces=0;		// no decimal places on the last price pointer

	//create the renderer
	var renderer=stxx.setSeriesRenderer(new CIQ.Renderer.Lines({params:{name:"my-renderer", type:"mountain", yAxis:axis}}));

	// create your series and attach them to the chart when the data is loaded.
	stxx.addSeries("NOK", {display:"NOK",width:4},function(){
		renderer.attachSeries("NOK", "#FFBE00").ready();
	});

	stxx.addSeries("SNE", {display:"Sony",width:4},function(){
		renderer.attachSeries("SNE", "#FF9300").ready();
	});

construct(config)

Default constructor for a renderer. Override this if desired.

Parameters:
Name Type Description
config object

Configuration for the renderer.

Properties
Name Type Argument Description
callback function <optional>

Callback function to perform activity post-drawing, for example, creating a legend. It will be called with an object containing the list of instruments and corresponding colors.
id string <optional>

Handle to access the rendering in the future. If not provided, one will be generated.
params object <optional>

Parameters to control the renderer itself

Properties
Name Type Argument Default Description
name string <optional>
 "Data"

Name of the renderer. This is used when displaying error message on screen
panel string <optional>
 "chart"

The name of the panel to put the rendering on.
overChart boolean <optional>
 true

If set to false, will draw the rendering behind the main chart rather than over it. By default, rendering will be as overlay on the main chart.
yAxis boolean <optional>

Y-axis object to use for the series.
opacity number <optional>
 1

Opacity of the rendering as a whole. Can be overridden by an opacity set for a series. Valid values are 0.0-1.0.
Not applicable on Lines with a type of mountain; use an "RGBA" color instead.
binding object <optional>

Allows the use of the study output colors within the renderer. See an example in the Using Renderers to Display Study Output section of the Studies tutorial.
Since:

  • 5.2.0 config.params.binding parameter added.

Inherited From:
Overrides:
Example
// add multiple series and attach to a custom y-axis on the left.
	// See this example working here : https://jsfiddle.net/chartiq/b6pkzrad

	// note how the addSeries callback is used to ensure the data is present before the series is displayed

	//create the custom axis
	var axis=new CIQ.ChartEngine.YAxis();
	axis.position="left";
	axis.textStyle="#FFBE00";
	axis.decimalPlaces=0;			// no decimal places on the axis labels
	axis.maxDecimalPlaces=0;		// no decimal places on the last price pointer

	//create the renderer
	var renderer=stxx.setSeriesRenderer(new CIQ.Renderer.Lines({params:{name:"my-renderer", type:"mountain", yAxis:axis}}));

	// create your series and attach them to the chart when the data is loaded.
	stxx.addSeries("NOK", {display:"NOK",width:4},function(){
		renderer.attachSeries("NOK", "#FFBE00").ready();
	});

	stxx.addSeries("SNE", {display:"Sony",width:4},function(){
		renderer.attachSeries("SNE", "#FF9300").ready();
	});

draw()

Perform drawing operations here.

Inherited From:
Overrides:

drawIndividualSeries(chart [, parameters])

Draws one series from the renderer.

Called by CIQ.ChartEngine.AdvancedInjectable#drawSeries

Parameters:
Name Type Argument Description
chart CIQ.ChartEngine.Chart

The chart object to draw the renderers upon
parameters object <optional>

Parameters used to draw the series, depends on the renderer type

Properties
Name Type Argument Description
panel string <optional>

Name of panel to draw the series upon
Since:

  • 5.1.0

Inherited From:
Overrides:

drawLabels()

Draws labels for Histogram and Lines renderers. It calculates the positions of the labels and draws them on the chart for series that have been created with the "labels" property. Labels property object can contain aditional overrides such as backgroundColor, textColor, padding, vertical offset and font

Since:

  • 9.6.0

Inherited From:
Overrides:

getDependents(stx)

Returns an array of all renderers that depend on a given renderer.

A dependent renderer is one that has params.dependentOf set to another renderer's name.

Parameters:
Name Type Description
stx CIQ.ChartEngine

A chart object.
Since:

  • 7.3.0

Inherited From:
Overrides:
Returns:

Array of dependent renderers.

Type
array

getYAxis(stx)

Returns the y-axis used by the renderer.

Parameters:
Name Type Description
stx CIQ.ChartEngine

chart engine object
Since:

  • 7.1.0

Inherited From:
Overrides:
Returns:

Y-axis

Type
CIQ.ChartEngine.YAxis

isHistogram()

Checks if the renderer represents a histogram.

Since:

  • 9.8.0

Inherited From:
Overrides:
Returns:

True if the renderer is a histogram.

Type
boolean

isScatter()

Checks if the renderer represents a scatter plot.

Since:

  • 9.8.0

Inherited From:
Overrides:
Returns:

True if the renderer is a scatter plot.

Type
boolean

performCalculations()

This function is no longer used by the library. Use CIQ.Renderer#adjustYAxis instead.

Inherited From:
Overrides:
Deprecated:

  • As of 5.2.0. no longer used in library..

ready()

Call this to immediately render the visualization, at the end of a chain of commands.

Inherited From:
Overrides:
Returns:

A copy of this for chaining

Type
CIQ.Renderer

removeAllSeries( [eraseData])

Removes all series from the renderer and the y-axis from the panel if it is not being used by any current renderers.

Parameters:
Name Type Argument Default Description
eraseData boolean <optional>
 false

Set to true to erase the actual series data in the CIQ.ChartEngine otherwise it will be retained
Inherited From:
Overrides:
Returns:

A copy of this for chaining

Type
CIQ.Renderer

removeSeries(id [, preserveSeries])

Removes a series from the renderer.

The yAxis and actual series data will also be removed if no longer used by any other renderers. When the last series is removed from the renderer, the chart it is attached to will remove the renderer. Will turn off comparison mode if there are no more comparisons on the chart if CIQ.ChartEngine.Chart#forcePercentComparison is true.

Parameters:
Name Type Argument Default Description
id string

The field name of the series.
preserveSeries boolean <optional>
 false

Set to true to keep the series data in the CIQ.ChartEngine objects, otherwise it will be deleted.
Since:
  • 2015-07-01 'preserveSeries' is now available.
  • 3.0.0 Series is now removed even if series parameter permanent is set to true. The permanent parameter only prevents right click user interaction and not programmatically requested removals.
  • 4.0.0 Series data is now totally removed from masterData if no longer used by any other renderers.
  • 6.2.0 No longer force 'percent'/'linear', when adding/removing comparison series, respectively, unless CIQ.ChartEngine.Chart#forcePercentComparison is true. This allows for backwards compatibility with previous UI modules.
Inherited From:
Overrides:
Returns:

A copy of this for chaining

Type
CIQ.Renderer

undraggable(stx)

Returns whether the renderer can be dragged to another axis or panel.

Parameters:
Name Type Description
stx CIQ.ChartEngine

A chart object.
Since:

  • 7.3.0

Inherited From:
Overrides:
Returns:

true, if not allowed to drag.

Type
boolean