new Series(chart, options)
This is the base series prototype that all other series types inherit from. A new series is initialized either through the series option structure, or after the chart is initialized, through Highcharts.Chart#addSeries.
The object can be accessed in a number of ways. All series and point event
handlers give a reference to the series object. The chart object has a
series property that is a collection of all
the chart's series. The point objects and axis objects also have the same
reference.
Another way to reference the series programmatically is by id. Add an id
in the series configuration options, and get the series object by
Highcharts.Chart#get.
Configuration options for the series are given in three levels. Options for
all series in a chart are given in the
plotOptions.series
object. Then options for all series of a specific type
are given in the plotOptions of that type, for example plotOptions.line.
Next, options for one single series are given in the series array, or as
arguments to chart.addSeries.
The data in the series is stored in various arrays.
-
First,
series.options.datacontains all the original config options for each point whether added by options or methods likeseries.addPoint. -
Next,
series.datacontains those values converted to points, but in case the series data length exceeds thecropThreshold, or if the data is grouped,series.datadoesn't contain all the points. It only contains the points that have been created on demand. -
Then there's
series.pointsthat contains all currently visible point objects. In case of cropping, the cropped-away points are not part of this array. Theseries.pointsarray starts atseries.cropStartcompared toseries.dataandseries.options.data. If however the series data is grouped, these can't be correlated one to one. -
series.xDataandseries.processedXDatacontain clean x values, equivalent toseries.dataandseries.points. -
series.yDataandseries.processedYDatacontain clean y values, equivalent toseries.dataandseries.points.
Parameters:
| Name | Type | Description |
|---|---|---|
chart |
Highcharts.Chart | The chart instance. |
options |
Highcharts.SeriesOptionsType | object | The series options. |
Members
-
chart :Highcharts.Chart
-
Read only. The chart that the series belongs to.
Type:
-
data :Array.<Highcharts.Point>
-
Read only. An array containing those values converted to points. In case the series data length exceeds the
cropThreshold, or if the data is grouped,series.datadoesn't contain all the points. Also, in case a series is hidden, thedataarray may be empty. To access raw values,series.options.datawill always be up to date.Series.dataonly contains the points that have been created on demand. To modify the data, use Highcharts.Series#setData or Highcharts.Point#update.Type:
- Array.<Highcharts.Point>
- See also:
-
- Highcharts.Series.points
-
<readonly> dataMax :number|undefined
-
Contains the maximum value of the series' data point. Some series types like
networkgraphdo not support this property as they lack ay-value.Type:
- number | undefined
-
<readonly> dataMin :number|undefined
-
Contains the minimum value of the series' data point. Some series types like
networkgraphdo not support this property as they lack ay-value.Type:
- number | undefined
-
<readonly> index :number
-
Contains the series' index in the
Chart.seriesarray.Type:
- number
-
name :string
-
The series name as given in the options. Defaults to "Series {n}".
Type:
- string
-
options :Highcharts.SeriesOptionsType
-
Read only. The series' current options. To update, use Highcharts.Series#update.
Type:
-
points :Array.<Highcharts.Point>
-
An array containing all currently visible point objects. In case of cropping, the cropped-away points are not part of this array. The
series.pointsarray starts atseries.cropStartcompared toseries.dataandseries.options.data. If however the series data is grouped, these can't be correlated one to one. To modify the data, use Highcharts.Series#setData or Highcharts.Point#update.Type:
- Array.<Highcharts.Point>
-
selected :boolean
-
Read only. The series' selected state as set by Highcharts.Series#select.
Type:
- boolean
-
type :string
-
Read only. The series' type, like "line", "area", "column" etc. The type in the series options anc can be altered using Highcharts.Series#update.
Type:
- string
-
userOptions :Highcharts.SeriesOptionsType
-
Contains series options by the user without defaults.
Type:
-
visible :boolean
-
Read only. The series' visibility state as set by Highcharts.Series#show, Highcharts.Series#hide, or in the initial configuration.
Type:
- boolean
-
xAxis :Highcharts.Axis
-
Read only. The unique xAxis object associated with the series.
Type:
-
yAxis :Highcharts.Axis
-
Read only. The unique yAxis object associated with the series.
Type:
Methods
-
addPoint(options [, redraw] [, shift] [, animation] [, withEvent])
-
Add a point to the series after render time. The point can be added at the end, or by giving it an X value, to the start or in the middle of the series.
Parameters:
Name Type Argument Default Description optionsHighcharts.PointOptionsType The point options. If options is a single number, a point with that y value is appended to the series. If it is an array, it will be interpreted as x and y values respectively. If it is an object, advanced options as outlined under
series.dataare applied.redrawboolean <optional>
true Whether to redraw the chart after the point is added. When adding more than one point, it is highly recommended that the redraw option be set to false, and instead Highcharts.Chart#redraw is explicitly called after the adding of points is finished. Otherwise, the chart will redraw after adding each point.
shiftboolean <optional>
false If true, a point is shifted off the start of the series as one is appended to the end.
animationboolean | Partial.<Highcharts.AnimationOptionsObject> <optional>
Whether to apply animation, and optionally animation configuration.
withEventboolean <optional>
true Used internally, whether to fire the series
addPointevent.Fires:
- Highcharts.Series#event:addPoint
Try it
-
animate( [init])
-
Animate in the series. Called internally twice. First with the
initparameter set to true, which sets up the initial state of the animation. Then when ready, it is called with theinitparameter undefined, in order to perform the actual animation. After the second run, the function is removed.Parameters:
Name Type Argument Description initboolean <optional>
Initialize the animation.
-
drawPoints()
-
Draw the markers for line-like series types, and columns or other graphical representation for Highcharts.Point objects for other series types. The resulting element is typically stored as Highcharts.Point.graphic, and is created on the first call and updated and moved on subsequent calls.
-
getName()
-
Return series name in "Series {Number}" format or the one defined by a user. This method can be simply overridden as series name format can vary (e.g. technical indicators).
Returns:
string .The series name.
-
getPlotBox()
-
Get the translation and scale for the plot area of this series.
Returns:
-
getValidPoints( [points] [, insideOnly] [, allowNull])
-
Return the series points with null points filtered out.
Parameters:
Name Type Argument Default Description pointsArray.<Highcharts.Point> <optional>
The points to inspect, defaults to Highcharts.Series.points.
insideOnlyboolean <optional>
false Whether to inspect only the points that are inside the visible view.
allowNullboolean <optional>
false Whether to allow null points to pass as valid points.
Returns:
Array.<Highcharts.Point> .The valid points.
-
hide()
-
Hide the series if visible. If the chart.ignoreHiddenSeries option is true, the chart is redrawn without this series.
Fires:
- Highcharts.Series#event:hide
Try it
-
is(type)
-
Check whether the series item is itself or inherits from a certain series type.
Parameters:
Name Type Description typestring The type of series to check for, can be either featured or custom series types. For example
column,pie,ohlcetc.Returns:
boolean .True if this item is or inherits from the given type.
-
markerAttribs(point [, state])
-
Get non-presentational attributes for a point. Used internally for both styled mode and classic. Can be overridden for different series types.
Parameters:
Name Type Argument Description pointHighcharts.Point The Point to inspect.
statestring <optional>
The state, can be either
hover,selector undefined.- See also:
-
- Highcharts.Series#pointAttribs
Returns:
Highcharts.SVGAttributes .A hash containing those attributes that are not settable from CSS.
-
onMouseOut()
-
Runs on mouse out of the series graphical items.
Fires:
- Highcharts.Series#event:mouseOut
-
onMouseOver()
-
Runs on mouse over the series graphical items.
Fires:
- Highcharts.Series#event:mouseOver
-
remove( [redraw] [, animation] [, withEvent])
-
Remove a series and optionally redraw the chart.
Parameters:
Name Type Argument Default Description redrawboolean <optional>
true Whether to redraw the chart or wait for an explicit call to Highcharts.Chart#redraw.
animationboolean | Partial.<Highcharts.AnimationOptionsObject> <optional>
Whether to apply animation, and optionally animation configuration.
withEventboolean <optional>
true Used internally, whether to fire the series
removeevent.Fires:
- Highcharts.Series#event:remove
Try it
-
removePoint(i [, redraw] [, animation])
-
Remove a point from the series. Unlike the Highcharts.Point#remove method, this can also be done on a point that is not instanciated because it is outside the view or subject to Highstock data grouping.
Parameters:
Name Type Argument Default Description inumber The index of the point in the data array.
redrawboolean <optional>
true Whether to redraw the chart after the point is added. When removing more than one point, it is highly recommended that the
redrawoption be set tofalse, and instead Highcharts.Chart#redraw is explicitly called after the adding of points is finished.animationboolean | Partial.<Highcharts.AnimationOptionsObject> <optional>
Whether and optionally how the series should be animated.
Fires:
- Highcharts.Point#event:remove
Try it
-
render()
-
Render the graph and markers. Called internally when first rendering and later when redrawing the chart. This function can be extended in plugins, but normally shouldn't be called directly.
Fires:
- Highcharts.Series#event:afterRender
-
select( [selected])
-
Select or unselect the series. This means its selected property is set, the checkbox in the legend is toggled and when selected, the series is returned by the Highcharts.Chart#getSelectedSeries function.
Parameters:
Name Type Argument Description selectedboolean <optional>
True to select the series, false to unselect. If undefined, the selection state is toggled.
Fires:
- Highcharts.Series#event:select
- Highcharts.Series#event:unselect
Try it
-
setCompare( [compare])
-
Highstock only. Set the compare mode of the series after render time. In most cases it is more useful running Highcharts.Axis#setCompare on the X axis to update all its series.
Parameters:
Name Type Argument Description comparestring <optional>
Can be one of
null(default),"percent"or"value". -
setData(data [, redraw] [, animation] [, updatePoints])
-
Apply a new set of data to the series and optionally redraw it. The new data array is passed by reference (except in case of
updatePoints), and may later be mutated when updating the chart data.Note the difference in behaviour when setting the same amount of points, or a different amount of points, as handled by the
updatePointsparameter.Parameters:
Name Type Argument Default Description dataArray.<Highcharts.PointOptionsType> Takes an array of data in the same format as described under
series.{type}.datafor the given series type, for example a line series would take data in the form described under series.line.data.redrawboolean <optional>
true Whether to redraw the chart after the series is altered. If doing more operations on the chart, it is a good idea to set redraw to false and call Highcharts.Chart#redraw after.
animationboolean | Partial.<Highcharts.AnimationOptionsObject> <optional>
When the updated data is the same length as the existing data, points will be updated by default, and animation visualizes how the points are changed. Set false to disable animation, or a configuration object to set duration or easing.
updatePointsboolean <optional>
true When this is true, points will be updated instead of replaced whenever possible. This occurs a) when the updated data is the same length as the existing data, b) when points are matched by their id's, or c) when points can be matched by X values. This allows updating with animation and performs better. In this case, the original array is not passed by reference. Set
falseto prevent.Try it
-
setState( [state] [, inherit])
-
Set the state of the series. Called internally on mouse interaction operations, but it can also be called directly to visually highlight a series.
Parameters:
Name Type Argument Description stateHighcharts.SeriesStateValue | "" <optional>
The new state, can be either
'hover','inactive','select', or''(an empty string),'normal'orundefinedto set to normal state.inheritboolean <optional>
Determines if state should be inherited by points too.
-
setVisible( [visible] [, redraw])
-
Show or hide the series.
Parameters:
Name Type Argument Default Description visibleboolean <optional>
True to show the series, false to hide. If undefined, the visibility is toggled.
redrawboolean <optional>
true Whether to redraw the chart after the series is altered. If doing more operations on the chart, it is a good idea to set redraw to false and call chart.redraw() after.
Fires:
- Highcharts.Series#event:hide
- Highcharts.Series#event:show
-
show()
-
Show the series if hidden.
Fires:
- Highcharts.Series#event:show
Try it
-
sonify( [options])
-
Sonify a series.
Parameters:
Name Type Argument Description optionsHighcharts.SonifySeriesOptionsObject <optional>
The options for sonifying this series. If not provided, uses options set on chart and series.
Requires:
- module:modules/sonification
Returns:
Try it
-
translate()
-
Translate data points from raw data values to chart specific positioning data needed later in the
drawPointsanddrawGraphfunctions. This function can be overridden in plugins and custom series type implementations.Fires:
- Highcharts.Series#events:translate
-
update(options [, redraw])
-
Update the series with a new set of options. For a clean and precise handling of new options, all methods and elements from the series are removed, and it is initialized from scratch. Therefore, this method is more performance expensive than some other utility methods like Highcharts.Series#setData or Highcharts.Series#setVisible.
Note that
Series.updatemay mutate the passeddataoptions.Parameters:
Name Type Argument Default Description optionsHighcharts.SeriesOptionsType New options that will be merged with the series' existing options.
redrawboolean <optional>
true Whether to redraw the chart after the series is altered. If doing more operations on the chart, it is a good idea to set redraw to false and call Highcharts.Chart#redraw after.
Fires:
- Highcharts.Series#event:update
- Highcharts.Series#event:afterUpdate
Try it