`.gauge`

class: `GaugeSeries`

class GaugeSeries(**kwargs)[source]

Options to configure a Gauge series.

Gauges are circular plots displaying one or more values with a dial pointing to values along the perimeter.

Class Inheritance

copy(other=None, overwrite=True, **kwargs)

Copy the configuration settings from this instance to the other instance.

Parameters:

other (HighchartsMeta) – The target instance to which the properties of this instance should be copied. If None, will create a new instance and populate it with properties copied from self. Defaults to None.
overwrite (bool) – if True, properties in other that are already set will be overwritten by their counterparts in self. Defaults to True.
kwargs – Additional keyword arguments. Some special descendents of HighchartsMeta may have special implementations of this method which rely on additional keyword arguments.

Returns:

A mutated version of other with new property values

classmethod from_csv(as_string_or_file, property_column_map, has_header_row=True, series_kwargs=None, delimiter=',', null_text='None', wrapper_character="'", line_terminator='\r\n', wrap_all_strings=False, double_wrapper_character_when_nested=False, escape_character='\\')

Create a new series instance with a .data property populated from data in a CSV string or file.

Note

For an example LineSeries, the minimum code required would be:
my_series = LineSeries.from_csv('some-csv-file.csv',
                                property_column_map = {
                                    'x': 0,
                                    'y': 3,
                                    'id': 'id'
                                })
As the example above shows, data is loaded into the my_series instance from the CSV file with a filename some-csv-file.csv. The x values for each data point will be taken from the first (index 0) column in the CSV file. The y values will be taken from the fourth (index 3) column in the CSV file. And the id values will be taken from a column whose header row is labeled 'id' (regardless of its index).

Parameters:

as_string_or_file (str or Path-like) –
The CSV data to use to pouplate data. Accepts either the raw CSV data as a str or a path to a file in the runtime environment that contains the CSV data.

Tip

Unwrapped empty column values are automatically interpreted as null (None).
property_column_map (dict) –
A dict used to indicate which data point property should be set to which CSV column. The keys in the dict should correspond to properties in the data point class, while the value can either be a numerical index (starting with 0) or a str indicating the label for the CSV column.

Warning

If the property_column_map uses str values, the CSV file must have a header row (this is expected, by default). If there is no header row and a str value is found, a HighchartsCSVDeserializationError will be raised.
has_header_row (bool) – If True, indicates that the first row of as_string_or_file contains column labels, rather than actual data. Defaults to True.
series_kwargs (dict) –
An optional dict containing keyword arguments that should be used when instantiating the series instance. Defaults to None.

Warning

If series_kwargs contains a data key, its value will be overwritten. The data value will be created from the CSV file instead.
delimiter (str) – The delimiter used between columns. Defaults to ,.
wrapper_character (str) – The string used to wrap string values when wrapping is applied. Defaults to '.
null_text (str) – The string used to indicate an empty value if empty values are wrapped. Defaults to None.
line_terminator (str) – The string used to indicate the end of a line/record in the CSV data. Defaults to '\r\n'.
line_terminator –
The string used to indicate the end of a line/record in the CSV data. Defaults to '\r\n'.

Note

The Python csv currently ignores the line_terminator parameter and always applies '\r\n', by design. The Python docs say this may change in the future, so for future backwards compatibility we are including it here.
wrap_all_strings (bool) –
If True, indicates that the CSV file has all string data values wrapped in quotation marks. Defaults to False.

Warning

If set to True, the csv module will try to coerce any value that is not wrapped in quotation marks to a float. This can cause unexpected behavior, and typically we recommend leaving this as False and then re-casting values after they have been parsed.
double_wrapper_character_when_nested (bool) – If True, quote character is doubled when appearing within a string value. If False, the escape_character is used to prefix quotation marks. Defaults to False.
escape_character (str) – A one-character string that indicates the character used to escape quotation marks if they appear within a string value that is already wrapped in quotation marks. Defaults to \\ (which is Python for '\', which is Python’s native escape character).

Returns:

A series instance (descended from SeriesBase) with its .data property populated from the CSV data in as_string_or_file.

Return type:

list of series instances (descended from SeriesBase)

Raises:

HighchartsCSVDeserializationError – if property_column_map references CSV columns by their label, but the CSV data does not contain a header row

classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)

Construct an instance of the class from a dict object.

Parameters:

as_dict (dict) – A dict representation of the object.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python object representation of as_dict.

Return type:

HighchartsMeta

classmethod from_js_literal(as_str_or_file, allow_snake_case: bool = True, _break_loop_on_failure: bool = False)

Return a Python object representation of a Highcharts JavaScript object literal.

Parameters:

as_str_or_file (str) – The JavaScript object literal, represented either as a str or as a filename which contains the JS object literal.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.
_break_loop_on_failure (bool) – If True, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults to False.

Returns:

A Python object representation of the Highcharts JavaScript object literal.

Return type:

HighchartsMeta

classmethod from_json(as_json_or_file, allow_snake_case: bool = True)

Construct an instance of the class from a JSON string.

Parameters:

as_json_or_file – The JSON string for the object or the filename of a file that contains the JSON string.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python objcet representation of as_json.

Return type:

HighchartsMeta

classmethod from_pandas(df, property_map, series_kwargs=None)

Create a series instance whose .data property is populated from a pandas DataFrame.

Parameters:

df (DataFrame) – The DataFrame from which data should be loaded.
property_map (dict) – A dict used to indicate which data point property should be set to which column in df. The keys in the dict should correspond to properties in the data point class, while the value should indicate the label for the DataFrame column.
series_kwargs (dict) –
An optional dict containing keyword arguments that should be used when instantiating the series instance. Defaults to None.

Warning

If series_kwargs contains a data key, its value will be overwritten. The data value will be created from df instead.

Returns:

A series instance (descended from SeriesBase) with its .data property populated from the data in df.

Return type:

list of series instances (descended from SeriesBase)

Raises:

HighchartsPandasDeserializationError – if property_map references a column that does not exist in the data frame
HighchartsDependencyError –
if pandas is not available in the runtime environment

classmethod from_pyspark(df, property_map, series_kwargs=None)

Create a series instance whose .data property is populated from a PySpark DataFrame.

Parameters:

df (DataFrame) – The DataFrame from which data should be loaded.
property_map (dict) – A dict used to indicate which data point property should be set to which column in df. The keys in the dict should correspond to properties in the data point class, while the value should indicate the label for the DataFrame column.
series_kwargs (dict) –
An optional dict containing keyword arguments that should be used when instantiating the series instance. Defaults to None.

Warning

If series_kwargs contains a data key, its value will be overwritten. The data value will be created from df instead.

Returns:

A series instance (descended from SeriesBase) with its .data property populated from the data in df.

Return type:

list of series instances (descended from SeriesBase)

Raises:

HighchartsPySparkDeserializationError – if property_map references a column that does not exist in the data frame
HighchartsDependencyError –
if PySpark is not available in the runtime environment

load_from_csv(as_string_or_file, property_column_map, has_header_row=True, delimiter=',', null_text='None', wrapper_character="'", line_terminator='\r\n', wrap_all_strings=False, double_wrapper_character_when_nested=False, escape_character='\\')

Replace the existing .data property with a new value populated from data in a CSV string or file.

Note

For an example LineSeries, the minimum code required would be:
my_series = LineSeries()
my_series = my_series.from_csv('some-csv-file.csv',
                               property_column_map = {
                                   'x': 0,
                                   'y': 3,
                                   'id': 'id'
                               })
As the example above shows, data is loaded into the my_series instance from the CSV file with a filename some-csv-file.csv. The x values for each data point will be taken from the first (index 0) column in the CSV file. The y values will be taken from the fourth (index 3) column in the CSV file. And the id values will be taken from a column whose header row is labeled 'id' (regardless of its index).

Parameters:

as_string_or_file (str or Path-like) –
The CSV data to use to pouplate data. Accepts either the raw CSV data as a str or a path to a file in the runtime environment that contains the CSV data.

Tip

Unwrapped empty column values are automatically interpreted as null (None).
property_column_map (dict) –
A dict used to indicate which data point property should be set to which CSV column. The keys in the dict should correspond to properties in the data point class, while the value can either be a numerical index (starting with 0) or a str indicating the label for the CSV column.

Warning

If the property_column_map uses str values, the CSV file must have a header row (this is expected, by default). If there is no header row and a str value is found, a HighchartsCSVDeserializationError will be raised.
has_header_row (bool) – If True, indicates that the first row of as_string_or_file contains column labels, rather than actual data. Defaults to True.
delimiter (str) – The delimiter used between columns. Defaults to ,.
wrapper_character (str) – The string used to wrap string values when wrapping is applied. Defaults to '.
null_text (str) – The string used to indicate an empty value if empty values are wrapped. Defaults to None.
line_terminator (str) – The string used to indicate the end of a line/record in the CSV data. Defaults to '\r\n'.
line_terminator –
The string used to indicate the end of a line/record in the CSV data. Defaults to '\r\n'.

Note

The Python csv currently ignores the line_terminator parameter and always applies '\r\n', by design. The Python docs say this may change in the future, so for future backwards compatibility we are including it here.
wrap_all_strings (bool) –
If True, indicates that the CSV file has all string data values wrapped in quotation marks. Defaults to False.

Warning

If set to True, the csv module will try to coerce any value that is not wrapped in quotation marks to a float. This can cause unexpected behavior, and typically we recommend leaving this as False and then re-casting values after they have been parsed.
double_wrapper_character_when_nested (bool) – If True, quote character is doubled when appearing within a string value. If False, the escape_character is used to prefix quotation marks. Defaults to False.
escape_character (str) – A one-character string that indicates the character used to escape quotation marks if they appear within a string value that is already wrapped in quotation marks. Defaults to \ (which is Python for '', which is Python’s native escape character).

Raises:

HighchartsCSVDeserializationError – if property_column_map references CSV columns by their label, but the CSV data does not contain a header row

load_from_pandas(df, property_map)

Replace the contents of the .data property with data points populated from a pandas DataFrame.

Parameters:

df (DataFrame) – The DataFrame from which data should be loaded.
property_map (dict) – A dict used to indicate which data point property should be set to which column in df. The keys in the dict should correspond to properties in the data point class, while the value should indicate the label for the DataFrame column.

Raises:

HighchartsPandasDeserializationError – if property_map references a column that does not exist in the data frame
HighchartsDependencyError –
if pandas is not available in the runtime environment

load_from_pyspark(df, property_map)

Replaces the contents of the .data property with values from a PySpark DataFrame.

Parameters:

df (DataFrame) – The DataFrame from which data should be loaded.
property_map (dict) – A dict used to indicate which data point property should be set to which column in df. The keys in the dict should correspond to properties in the data point class, while the value should indicate the label for the DataFrame column.

Raises:

HighchartsPySparkDeserializationError – if property_map references a column that does not exist in the data frame
HighchartsDependencyError –
if PySpark is not available in the runtime environment

to_dict() → dict

Generate a dict representation of the object compatible with the Highcharts JavaScript library.

Note

The dict representation has a property structure and naming convention that is intentionally consistent with the Highcharts JavaScript library. This is not Pythonic, but it makes managing the interplay between the two languages much, much simpler.

Returns:: A dict representation of the object.
Return type:: dict

to_js_literal(filename=None, encoding='utf-8') → str | None

Return the object represented as a str containing the JavaScript object literal.

Parameters:

filename (Path-like) – The name of a file to which the JavaScript object literal should be persisted. Defaults to None
encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

Return type:

str or None

to_json(filename=None, encoding='utf-8')

Generate a JSON string/byte string representation of the object compatible with the Highcharts JavaScript library.

Note

This method will either return a standard str or a bytes object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be a bytes representation of the string.

Parameters:

filename (Path-like) – The name of a file to which the JSON string should be persisted. Defaults to None
encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

Returns:

A JSON representation of the object compatible with the Highcharts library.

Return type:

str or bytes

static trim_dict(untrimmed: dict, to_json: bool = False) → dict

Remove keys from untrimmed whose values are None and convert values that have .to_dict() methods.

Parameters:

untrimmed (dict) – The dict whose values may still be None or Python objects.
to_json (bool) – If True, will remove all keys from untrimmed that are not serializable to JSON. Defaults to False.

Returns:

Trimmed dict

Return type:

dict

static trim_iterable(untrimmed, to_json=False)

Convert any EnforcedNullType values in untrimmed to 'null'.

Parameters:

untrimmed (iterable) – The iterable whose members may still be None or Python objects.
to_json (bool) – If True, will remove all members from untrimmed that are not serializable to JSON. Defaults to False.

Return type:

iterable

property accessibility: TypeOptionsAccessibility | None

Accessibility options for a series.

Return type:: TypeOptionsAccessibility or None

property allow_point_select: bool | None

Allow this series’ points to be selected by clicking on the graphic (columns, point markers, pie slices, map areas etc).

The selected points can be handled in JavaScript by point select and unselect events, or collectively by the (JavaScript) getSelectedPoints() function.

And alternative way of selecting points is through dragging.

Defaults to False.

Return type:: bool or None

property animation: AnimationOptions | None

Enable or disable the initial animation when a series is displayed.

The animation can also be set as a configuration object. Please note that this option only applies to the initial animation of the series itself. For other animations, see Chart.animation and the animation parameter under the (JavaScript) API methods. The following properties are supported:

defer: The animation delay time in milliseconds.

duration: The duration of the animation in milliseconds.

easing: Can be a string reference to an easing function set on the Math object or a function.

Warning

Due to poor performance, animation is disabled in old IE browsers for several chart types.

Return type:: AnimationOptions or None

property animation_limit: int | float | Decimal | None

For some series, there is a limit that shuts down initial animation by default when the total number of points in the chart is too high. Defaults to None.

For example, for a column chart and its derivatives, animation does not run if there is more than 250 points totally. To disable this cap, set animation_limit to float("inf") (which represents infinity).

Return type:: numeric or None

property boost_blending: str | None

Sets the color blending in the boost module. Defaults to None.

Return type:: str or None

property boost_threshold: int | None

Set the point threshold for when a series should enter boost mode. Defaults to 5000.

Setting it to e.g. 2000 will cause the series to enter boost mode when there are 2,000 or more points in the series.

To disable boosting on the series, set the boost_threshold to 0. Setting it to 1 will force boosting.

Note

The AreaOptions.crop_threshold() also affects this setting.

When zooming in on a series that has fewer points than the crop_threshold, all points are rendered although outside the visible plot area, and the boost_threshold won’t take effect.

Return type:: int or None

property class_name: str | None

The additional CSS class name to apply to the series’ graphical elements.

Note

This option is additive to the default class names - it does not replace them.

Return type:: str or None

property clip: bool | None

If False, allows the series to be rendered in the entire plot area. If True, constrains where the series can be rendered within the plot area. Defaults to True.

Return type:: bool or None

property color: str | Gradient | Pattern | None

The main color of the series.

In line type series it applies to the line and the point markers unless otherwise specified. In bar type series it applies to the bars unless a color is specified per point. The default value is pulled from the Options.colors() array.

Returns:: The main color applied to the series.
Return type:: str, Gradient, Pattern`, or None

property color_axis: str | int | bool | None

When using dual or multiple color axes, this setting defines which color axis the particular series is connected to. It refers to either the ColorAxis.id() or the index of the axis in the ColorAxis array, with 0 being the first. Set this option to False to prevent a series from connecting to the default color axis.

Defaults to 0.

Return type:: None or str or int or bool

property color_index: int | None

When operating in styled mode, a specific color index to use for the series, so that its graphic representations are given the class name highcharts-color-{n}.

Tip

New in version Highcharts: (JS) v.11

With Highcharts (JS) v.11, using CSS variables of the form --highcharts-color-{n} make changing the color scheme very simple.

Defaults to None.

Return type:: int or None

property color_key: str | None

Determines what data value should be used to calculate point color if AreaOptions.color_axis() is used.

Note

Requires to set min and max if some custom point property is used or if approximation for data grouping is set to 'sum'.

Return type:: str or None

property connect_ends: bool | None

If True, connect the ends of a line series plot across the extremes. Defaults to None.

Warning

Applies to polar charts only.

Return type:: bool or None

property connect_nulls: bool | None

If True, connect a graph line across null points. If False, renders a gap between the points on either side of the null point. Defaults to False.

Return type:: bool or None

property crisp: bool | None

If True, each point or column edge is rounded to its nearest pixel in order to render sharp on screen. Defaults to True.

Hint

In some cases, when there are a lot of densely packed columns, this leads to visible difference in column widths or distance between columns. In these cases, setting crisp to False may look better, even though each column is rendered blurry.

Return type:: bool or None

property crop_threshold: int | None

When the series contains less points than the crop threshold, all points are drawn, even if the points fall outside the visible plot area at the current zoom. Defaults to 300.

The advantage of drawing all points (including markers and columns), is that animation is performed on updates. On the other hand, when the series contains more points than the crop threshold, the series data is cropped to only contain points that fall within the plot area. The advantage of cropping away invisible points is to increase performance on large series.

Return type:: int or None

property cursor: str | None

The style of cursor to use when the user’s mouse hovers over the data series.

Acceptable values are:

'alias'

'all-scroll'

'auto'

'cell'

'col-resize'

'context-menu'

'copy'

'crosshair'

'default'

'e-resize'

'ew-resize'

'grab'

'grabbing'

'help'

'move'

'n-resize'

'ne-resize'

'nesw-resize'

'no-drop'

'none'

'not-allowed'

'ns-resize'

'nw-resize'

'nwse-resize'

'pointer'

'progress'

'row-resize'

's-resize'

'se-resize'

'sw-resize'

'text'

'vertical-text'

'w-resize'

'wait'

'zoom-in'

'zoom-out'

Return type:: str or None

property custom: JavaScriptDict | None

A reserved subspace to store options and values for customized functionality.

Here you can add additional data for your own event callbacks and formatter callbacks.

Return type:: dict or None

property dash_style: str | None

Name of the dash style to use for the graph, or for some series types the outline of each shape.

Accepts one of the following values:

‘Dash’,

‘DashDot’,

‘Dot’,

‘LongDash’,

‘LongDashDot’,

‘LongDashDotDot’,

‘ShortDash’,

‘ShortDashDot’,

‘ShortDashDotDot’,

‘ShortDot’,

‘Solid’

Return type:: str or None

property data: List[SinglePointData] | None

Collection of data that represents the series. Defaults to None.

While the series type returns a collection of SinglePointData instances, it accepts as input three different types of data:

series = PieSeries()
series.data = [0, 5, 3, 5]

A one-dimensional collection of numerical values. Each member of the collection will be interpreted as a y value

A one-dimensional collection of SinglePointData objects.

Return type:: list of SinglePointData or None

property data_labels: DataLabel | List[DataLabel] | None

Options for the series data labels, appearing next to each data point.

Note

To have multiple data labels per data point, you can also supply a collection of DataLabel configuration settings.

Return type:: DataLabel, list of DataLabel, or None

property data_sorting: DataSorting | None

Options for the series data sorting.

Return type:: DataSorting or None

property description: str | None

A description of the series to add to the screen reader information about the series.

Return type:: str or None

property dial: DialOptions | None

Options for the dial or arrow pointer of the gauge.

Return type:: DialOptions or None

property drag_drop: DragDropOptions | None

The draggable-points module allows points to be moved around or modified in the chart.

In addition to the options mentioned under the dragDrop API structure, the module fires three (JavaScript) events:

point.dragStart

point.drag

point.drop

Return type:: DragDropOptions or None

property enable_mouse_tracking: bool | None

If True, enables mouse tracking for the series (used to capture point tooltips, click events on graphs and points, etc.). If False, disables mouse tracking for the series (which can help performance). Defaults to True.

Return type:: bool or None

property events: SeriesEvents | None

General event handlers for the series items.

Note

These event hooks can also be attached to the series at run time using the (JavaScript) Highcharts.addEvent() function.

Return type:: SeriesEvents or None

property find_nearest_point_by: str | None

Determines whether the series should look for the nearest point in both dimensions or just the x-dimension when hovering the series.

If None, defaults to 'xy' for scatter series and 'x' for most other series. If the data has duplicate x-values, it is recommended to set this to 'xy' to allow hovering over all points.

Applies only to series types using nearest neighbor search (not direct hover) for tooltip.

Return type:: str or None

property get_extremes_from_all: bool | None

If True, uses the Y extremes of the total chart width or only the zoomed area when zooming in on parts of the X axis. By default, the Y axis adjusts to the min and max of the visible data.

Warning

Applies to Cartesian series only.

Return type:: bool or None

property id: str | None

An id for the series. Defaults to None.

Hint

This can be used (in JavaScript) after render time to get a pointer to the series object through chart.get().

Return type:: str or None

property include_in_data_export: bool | None

If False, will prevent the data series from being included in any form of data export. Defaults to True.

Return type:: bool or None

property index: int | None

The index for the series in the chart, affecting the internal index in the (JavaScript) chart.series array, the visible Z-index, and the order of the series in the legend. Defaults to None.

Return type:: int or None

property keys: List[str] | None

An array specifying which option maps to which key in the data point array.

This makes it convenient to work with unstructured data arrays from different sources.

Return type:: list of str, or None

property label: SeriesLabel | None

Series labels are placed as close to the series as possible in a natural way, seeking to avoid other series. The goal of this feature is to make the chart more easily readable, like if a human designer placed the labels in the optimal position.

Note

The series labels currently work with series types having a graph or an area.

Return type:: SeriesLabel or None

property legend_index: int | None

The sequential index for the series in the legend. Defaults to None.

Return type:: int or None

property line_width: int | float | Decimal | None

Pixel width of the graph line. Defaults to 2.

Return type:: numeric or None

property linecap: str | None

The SVG value used for the stroke-linecap and stroke-linejoin of a line graph. Defaults to 'round', which means that lines are rounded in the ends and bends.

Return type:: str or None

property linked_to: str | None

The id of another series to link to.

Hint

The value can be ':previous' to link to the previous series. When two series are linked, only the first one appears in the legend. Toggling the visibility of this also toggles the linked series.

Note

If the master series uses data sorting and linked series does not have its own sorting definition, the linked series will be sorted in the same order as the master one.

Return type:: str or None

property marker: Marker | None

Options for the point markers of line-like series.

Properties like fill_color, line_color and line_width define the visual appearance of the markers. Other series types, like column series, don’t have markers, but have visual options on the series level instead.

Return type:: Marker or None

property name: str | None

The name of the series as shown in the legend, tooltip, etc. Defaults to None.

Return type:: str or None

property negative_color: str | Gradient | Pattern | None

The color for the parts of the graph or points that are below the AreaOptions.threshold().

Note

Zones take precedence over the negative color. Using negative_color is equivalent to applying a zone with value of 0.

Return type:: None, Gradient, Pattern, or str

property on_point: OnPointOptions | None

Options for the Series on point feature, which is currently only supported by pie and sunburst chargs.

Return type:: OnPointOptions or None

property opacity: float | None

Opacity of a series parts: line, fill (e.g. area), and labels.

Return type:: float

property overshoot: int | float | Decimal | None

Allow the dial to overshoot the end of the perimeter axis by this many degrees.

For example, if this option is set to 5 and the gauge axis goes from 0 to 60, a value of 100, or 1000, will show 5 degrees beyond the end of the axis.

Defaults to None.

Return type:: numeric or None

property pivot: PivotOptions | None

Options for the pivot or the center point of the gauge.

Return type:: PivotOptions or None

property point: Point | None

Properties for each single point.

Return type:: Point or None

property point_description_formatter: CallbackFunction | None

Same as for Accessibility.series.description_formatter(), only for an individual series. Overrides the chart-wide configuration.

Return type:: CallbackFunction or None

property point_interval: int | float | Decimal | None

If no x values are given for the points in a series, point_interval defines the interval of the x values. Defaults to 1.

For example, if a series contains one value every decade starting from year 0, set point_interval to 10. In true datetime axes, the point_interval is set in milliseconds.

Hint

point_interval can be also be combined with point_interval_unit to draw irregular time intervals.

Note

If combined with relative_x_value, an x value can be set on each point, and the point_interval is added x times to the point_start setting.

Warning

This options applies to the series data, not the interval of the axis ticks, which is independent.

Return type:: numeric or None

property point_interval_unit: str | None

On datetime series, this allows for setting the point_interval to irregular time units, day, month, and year.

A day is usually the same as 24 hours, but point_interval_unit also takes the DST crossover into consideration when dealing with local time.

Combine this option with point_interval to draw weeks, quarters, 6 month periods, 10 year periods, etc.

Warning

This options applies to the series data, not the interval of the axis ticks, which is independent.

Return type:: str or None

property point_placement: str | int | float | Decimal | None

Used to determine the placement of the point in relation to tick marks on the X axis. Defaults to None, which behaves as undefined in cartesian charts, and "between" in polar charts.

Accepts possible values:

'on' - where the point will not create any padding of the X axis. In a polar column chart this means that the first column points directly north.

"between" - where the columns will be laid out between ticks. This is useful for example for visualising an amount between two points in time or in a certain sector of a polar chart.

a numeric value - where 0 is on the axis value, -0.5 is between this value and the previous, and 0.5 is between this value and the next. Unlike the textual options, numeric point placement options won’t affect axis padding.

Warning

Requires point_range to work. For column series this is computed, but for line-type series it needs to be set.

Note

For the xrange series type and gantt charts, if the Y axis is a category axis, the point_placement applies to the Y axis rather than the (typically datetime) X axis.

Return type:: str or None

property point_start: int | float | Decimal | None

If no x values are given for the points in a series, point_start defines on what value to start. For example, if a series contains one yearly value starting from 1945, set point_start to 1945. Defaults to 0.

Note

If combined with relative_x_value, an x value can be set on each point. The x value from the point options is multiplied by point_interval and added to point_start to produce a modified x value.

Return type:: numeric or None

property relative_x_value: bool | None

When True, X values in the data set are relative to the current point_start, point_interval, and point_interval_unit settings. This allows compression of the data for datasets with irregular X values. Defaults to False.

The real X values are computed on the formula f(x) = ax + b, where a is the point_interval (optionally with a time unit given by point_interval_unit), and b is the point_start.

Return type:: bool or None

property selected: bool | None

If True, the series is selected initially (by default, without user interaction). Defaults to False.

Note

If GenericTypeOptions.show_checkbox() is True, then the checkbox will be checked if selected is True.

Return type:: bool or None

property shadow: bool | ShadowOptions | None

Configuration for the shadow to apply to the tooltip. Defaults to False.

If False, no shadow is applied.

Returns:: The shadow configuration to apply or a boolean setting which hides the shadow or displays the default shadow.
Return type:: bool or ShadowOptions

property show_checkbox: bool | None

If True, a checkbox is displayed next to the legend item to allow selecting the series.

Note

The state of the checkbox is controlled by the GenericTypeOptions.selected() property.

Return type:: bool or None

property show_in_legend: bool | None

Whether to display this particular series or series type in the legend. Standalone series are shown in the legend by default, and linked series are not.

Return type:: bool or None

property skip_keyboard_navigation: bool | None

If True, the accessibility module will skip past this series when executing keyboard navigation.

Return type:: bool or None

property soft_threshold: bool | None

When True, the series will not cause the Y axis to cross the zero plane (or threshold option) unless the data actually crosses the plane. Defaults to True.

For example, if False, a series of 0, 1, 2, 3 will make the Y axis show negative values according to the min_padidng option. If True, the Y axis starts at 0.

Return type:: bool

property sonification: SeriesSonification | None

Sonification configuration for the series type/series.

Return type:: SeriesSonification or None

property stack: str | None

Indicates the “stack” into which the series should be grouped, if the chart groups series into stacks. Defaults to None.

Note

The value can be a string or a numeric value, provided that series in the same stack all have the same value when converted to a string. For ease of ues, Highcharts for Python will attempt to force the conversion of the relevant value to a string.

Return type:: str or None

property stacking: str | None

Whether to stack the values of each series on top of each other. Defaults to None.

Acceptable values are:

None to disable stacking,

"normal" to stack by value or

"percent"

'stream' (for streamgraph series type only)

'overlap' (for waterfall series type only)

Note

When stacking is enabled, data must be sorted in ascending X order.

Return type:: str or None

property states: States | None

Configuration for state-specific configuration to apply to the data series.

Return type:: States or None

property step: str | None

Whether to apply steps to the line. Defaults to None.

Possible values are:

None

'left'

'center'

'right'

Return type:: str or None

property sticky_tracking: bool | None

Sticky tracking of mouse events.

When True, the (JavaScript) mouseOut event on a series is not triggered until the mouse moves over another series, or out of the plot area.

When False, the (JavaScript) mouseOut event on a series is triggered when the mouse leaves the area around the series’ graph or markers. This also implies the tooltip when not shared.

When False and PlotOptions.tooltip.shared() is also False, the tooltip will be hidden when moving the mouse between series.

Defaults to True for line and area type series, but to False for columns, pies, etc.

Note

The boost module will force this option because of technical limitations.

Return type:: bool or None

property threshold: int | float | Decimal | EnforcedNullType | None

The Y axis value to serve as the base for the columns, for distinguishing between values above and below a threshold. Defaults to 0.

If EnforcedNullType, the columns extend from the padding Y axis minimum.

Return type:: numeric or EnforcedNullType or None

property tooltip: Tooltip | None

A configuration object for the tooltip rendering of each single series. Properties are inherited from tooltip, but only the following properties can be defined on a series level.

Return type:: Tooltip or None

property turbo_threshold: int | None

When a series contains a data array longer than this value, only one dimensional arrays of numbers, or two dimensional arrays with x and y values are allowed. Also, only the first point is tested, and the rest are assumed to be the same format. This saves expensive data checking and indexing in long series. Set it to 0 or None to disable.

Defaults to 1000.

Note

In boost mode, turbo threshold is forced. Only array of numbers or two dimensional arrays are allowed.

Return type:: int or None

property type: str

Indicates the type of series that is represented by this instance.

Warning

This proprety is read-only!

Return type:: str

property visible: bool | None

If True, the series is initially visible. If False, the series is hidden by default. Defaults to True.

Return type:: bool or None

property wrap: bool | None

When True, the dial will wrap around the axes. When wrap is False, the dial stops at 360. Defaults to True.

For instance, if True in a full-range gauge going from 0 to 360, a value of 400 will point to 40.

Return type:: bool or None

property x_axis: str | int | None

When using multiple X-axes, this setting determines on which axis the series should be drawn. Its value should be either a numerical index position in the Options.x_axis() array (starting at 0), or a str indicating the id of the axis to which the series should be connected. Defaults to None, which behaves as if the value were set to 0.

Return type:: str, int, or None

property y_axis: str | int | None

When using multiple Y-axes, this setting determines on which axis the series should be drawn. Its value should be either a numerical index position in the Options.y_axis() array (starting at 0), or a str indicating the id of the axis to which the series should be connected. Defaults to None, which behaves as if the value were set to 0.

Return type:: str, int, or None

property z_index: int | float | Decimal | None

The visual z-index of the series. Defaults to None.

Return type:: numeric or None

property zone_axis: str | None

Defines the Axis on which the zones are applied. Defaults to 'y'.

Return type:: str or None

property zones: List[Zone] | None

An array defining zones within a series. Defaults to None.

Zones can be applied to the X axis, Y axis or Z axis for bubbles, according to the zone_axis setting.

Warning

The zone definitions have to be in ascending order regarding to the value.

Return type:: None or list of Zone instances

class: `SolidGaugeSeries`

class SolidGaugeSeries(**kwargs)[source]

Options to configure a Solid Gauge series.

A solid gauge is a circular gauge where the value is indicated by a filled arc, and the color of the arc may variate with the value.

Class Inheritance

copy(other=None, overwrite=True, **kwargs)

Copy the configuration settings from this instance to the other instance.

Parameters:

other (HighchartsMeta) – The target instance to which the properties of this instance should be copied. If None, will create a new instance and populate it with properties copied from self. Defaults to None.
overwrite (bool) – if True, properties in other that are already set will be overwritten by their counterparts in self. Defaults to True.
kwargs – Additional keyword arguments. Some special descendents of HighchartsMeta may have special implementations of this method which rely on additional keyword arguments.

Returns:

A mutated version of other with new property values

classmethod from_csv(as_string_or_file, property_column_map, has_header_row=True, series_kwargs=None, delimiter=',', null_text='None', wrapper_character="'", line_terminator='\r\n', wrap_all_strings=False, double_wrapper_character_when_nested=False, escape_character='\\')

Create a new series instance with a .data property populated from data in a CSV string or file.

Note

For an example LineSeries, the minimum code required would be:
my_series = LineSeries.from_csv('some-csv-file.csv',
                                property_column_map = {
                                    'x': 0,
                                    'y': 3,
                                    'id': 'id'
                                })
As the example above shows, data is loaded into the my_series instance from the CSV file with a filename some-csv-file.csv. The x values for each data point will be taken from the first (index 0) column in the CSV file. The y values will be taken from the fourth (index 3) column in the CSV file. And the id values will be taken from a column whose header row is labeled 'id' (regardless of its index).

Parameters:

as_string_or_file (str or Path-like) –
The CSV data to use to pouplate data. Accepts either the raw CSV data as a str or a path to a file in the runtime environment that contains the CSV data.

Tip

Unwrapped empty column values are automatically interpreted as null (None).
property_column_map (dict) –
A dict used to indicate which data point property should be set to which CSV column. The keys in the dict should correspond to properties in the data point class, while the value can either be a numerical index (starting with 0) or a str indicating the label for the CSV column.

Warning

If the property_column_map uses str values, the CSV file must have a header row (this is expected, by default). If there is no header row and a str value is found, a HighchartsCSVDeserializationError will be raised.
has_header_row (bool) – If True, indicates that the first row of as_string_or_file contains column labels, rather than actual data. Defaults to True.
series_kwargs (dict) –
An optional dict containing keyword arguments that should be used when instantiating the series instance. Defaults to None.

Warning

If series_kwargs contains a data key, its value will be overwritten. The data value will be created from the CSV file instead.
delimiter (str) – The delimiter used between columns. Defaults to ,.
wrapper_character (str) – The string used to wrap string values when wrapping is applied. Defaults to '.
null_text (str) – The string used to indicate an empty value if empty values are wrapped. Defaults to None.
line_terminator (str) – The string used to indicate the end of a line/record in the CSV data. Defaults to '\r\n'.
line_terminator –
The string used to indicate the end of a line/record in the CSV data. Defaults to '\r\n'.

Note

The Python csv currently ignores the line_terminator parameter and always applies '\r\n', by design. The Python docs say this may change in the future, so for future backwards compatibility we are including it here.
wrap_all_strings (bool) –
If True, indicates that the CSV file has all string data values wrapped in quotation marks. Defaults to False.

Warning

If set to True, the csv module will try to coerce any value that is not wrapped in quotation marks to a float. This can cause unexpected behavior, and typically we recommend leaving this as False and then re-casting values after they have been parsed.
double_wrapper_character_when_nested (bool) – If True, quote character is doubled when appearing within a string value. If False, the escape_character is used to prefix quotation marks. Defaults to False.
escape_character (str) – A one-character string that indicates the character used to escape quotation marks if they appear within a string value that is already wrapped in quotation marks. Defaults to \\ (which is Python for '\', which is Python’s native escape character).

Returns:

A series instance (descended from SeriesBase) with its .data property populated from the CSV data in as_string_or_file.

Return type:

list of series instances (descended from SeriesBase)

Raises:

HighchartsCSVDeserializationError – if property_column_map references CSV columns by their label, but the CSV data does not contain a header row

classmethod from_dict(as_dict: dict, allow_snake_case: bool = True)

Construct an instance of the class from a dict object.

Parameters:

as_dict (dict) – A dict representation of the object.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python object representation of as_dict.

Return type:

HighchartsMeta

classmethod from_js_literal(as_str_or_file, allow_snake_case: bool = True, _break_loop_on_failure: bool = False)

Return a Python object representation of a Highcharts JavaScript object literal.

Parameters:

as_str_or_file (str) – The JavaScript object literal, represented either as a str or as a filename which contains the JS object literal.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.
_break_loop_on_failure (bool) – If True, will break any looping operations in the event of a failure. Otherwise, will attempt to repair the failure. Defaults to False.

Returns:

A Python object representation of the Highcharts JavaScript object literal.

Return type:

HighchartsMeta

classmethod from_json(as_json_or_file, allow_snake_case: bool = True)

Construct an instance of the class from a JSON string.

Parameters:

as_json_or_file – The JSON string for the object or the filename of a file that contains the JSON string.
allow_snake_case (bool) – If True, interprets snake_case keys as equivalent to camelCase keys. Defaults to True.

Returns:

A Python objcet representation of as_json.

Return type:

HighchartsMeta

classmethod from_pandas(df, property_map, series_kwargs=None)

Create a series instance whose .data property is populated from a pandas DataFrame.

Parameters:

df (DataFrame) – The DataFrame from which data should be loaded.
property_map (dict) – A dict used to indicate which data point property should be set to which column in df. The keys in the dict should correspond to properties in the data point class, while the value should indicate the label for the DataFrame column.
series_kwargs (dict) –
An optional dict containing keyword arguments that should be used when instantiating the series instance. Defaults to None.

Warning

If series_kwargs contains a data key, its value will be overwritten. The data value will be created from df instead.

Returns:

A series instance (descended from SeriesBase) with its .data property populated from the data in df.

Return type:

list of series instances (descended from SeriesBase)

Raises:

HighchartsPandasDeserializationError – if property_map references a column that does not exist in the data frame
HighchartsDependencyError –
if pandas is not available in the runtime environment

classmethod from_pyspark(df, property_map, series_kwargs=None)

Create a series instance whose .data property is populated from a PySpark DataFrame.

Parameters:

df (DataFrame) – The DataFrame from which data should be loaded.
property_map (dict) – A dict used to indicate which data point property should be set to which column in df. The keys in the dict should correspond to properties in the data point class, while the value should indicate the label for the DataFrame column.
series_kwargs (dict) –
An optional dict containing keyword arguments that should be used when instantiating the series instance. Defaults to None.

Warning

If series_kwargs contains a data key, its value will be overwritten. The data value will be created from df instead.

Returns:

A series instance (descended from SeriesBase) with its .data property populated from the data in df.

Return type:

list of series instances (descended from SeriesBase)

Raises:

HighchartsPySparkDeserializationError – if property_map references a column that does not exist in the data frame
HighchartsDependencyError –
if PySpark is not available in the runtime environment

load_from_csv(as_string_or_file, property_column_map, has_header_row=True, delimiter=',', null_text='None', wrapper_character="'", line_terminator='\r\n', wrap_all_strings=False, double_wrapper_character_when_nested=False, escape_character='\\')

Replace the existing .data property with a new value populated from data in a CSV string or file.

Note

For an example LineSeries, the minimum code required would be:
my_series = LineSeries()
my_series = my_series.from_csv('some-csv-file.csv',
                               property_column_map = {
                                   'x': 0,
                                   'y': 3,
                                   'id': 'id'
                               })
As the example above shows, data is loaded into the my_series instance from the CSV file with a filename some-csv-file.csv. The x values for each data point will be taken from the first (index 0) column in the CSV file. The y values will be taken from the fourth (index 3) column in the CSV file. And the id values will be taken from a column whose header row is labeled 'id' (regardless of its index).

Parameters:

as_string_or_file (str or Path-like) –
The CSV data to use to pouplate data. Accepts either the raw CSV data as a str or a path to a file in the runtime environment that contains the CSV data.

Tip

Unwrapped empty column values are automatically interpreted as null (None).
property_column_map (dict) –
A dict used to indicate which data point property should be set to which CSV column. The keys in the dict should correspond to properties in the data point class, while the value can either be a numerical index (starting with 0) or a str indicating the label for the CSV column.

Warning

If the property_column_map uses str values, the CSV file must have a header row (this is expected, by default). If there is no header row and a str value is found, a HighchartsCSVDeserializationError will be raised.
has_header_row (bool) – If True, indicates that the first row of as_string_or_file contains column labels, rather than actual data. Defaults to True.
delimiter (str) – The delimiter used between columns. Defaults to ,.
wrapper_character (str) – The string used to wrap string values when wrapping is applied. Defaults to '.
null_text (str) – The string used to indicate an empty value if empty values are wrapped. Defaults to None.
line_terminator (str) – The string used to indicate the end of a line/record in the CSV data. Defaults to '\r\n'.
line_terminator –
The string used to indicate the end of a line/record in the CSV data. Defaults to '\r\n'.

Note

The Python csv currently ignores the line_terminator parameter and always applies '\r\n', by design. The Python docs say this may change in the future, so for future backwards compatibility we are including it here.
wrap_all_strings (bool) –
If True, indicates that the CSV file has all string data values wrapped in quotation marks. Defaults to False.

Warning

If set to True, the csv module will try to coerce any value that is not wrapped in quotation marks to a float. This can cause unexpected behavior, and typically we recommend leaving this as False and then re-casting values after they have been parsed.
double_wrapper_character_when_nested (bool) – If True, quote character is doubled when appearing within a string value. If False, the escape_character is used to prefix quotation marks. Defaults to False.
escape_character (str) – A one-character string that indicates the character used to escape quotation marks if they appear within a string value that is already wrapped in quotation marks. Defaults to \ (which is Python for '', which is Python’s native escape character).

Raises:

HighchartsCSVDeserializationError – if property_column_map references CSV columns by their label, but the CSV data does not contain a header row

load_from_pandas(df, property_map)

Replace the contents of the .data property with data points populated from a pandas DataFrame.

Parameters:

df (DataFrame) – The DataFrame from which data should be loaded.
property_map (dict) – A dict used to indicate which data point property should be set to which column in df. The keys in the dict should correspond to properties in the data point class, while the value should indicate the label for the DataFrame column.

Raises:

HighchartsPandasDeserializationError – if property_map references a column that does not exist in the data frame
HighchartsDependencyError –
if pandas is not available in the runtime environment

load_from_pyspark(df, property_map)

Replaces the contents of the .data property with values from a PySpark DataFrame.

Parameters:

df (DataFrame) – The DataFrame from which data should be loaded.
property_map (dict) – A dict used to indicate which data point property should be set to which column in df. The keys in the dict should correspond to properties in the data point class, while the value should indicate the label for the DataFrame column.

Raises:

HighchartsPySparkDeserializationError – if property_map references a column that does not exist in the data frame
HighchartsDependencyError –
if PySpark is not available in the runtime environment

to_dict() → dict

Generate a dict representation of the object compatible with the Highcharts JavaScript library.

Note

The dict representation has a property structure and naming convention that is intentionally consistent with the Highcharts JavaScript library. This is not Pythonic, but it makes managing the interplay between the two languages much, much simpler.

Returns:: A dict representation of the object.
Return type:: dict

to_js_literal(filename=None, encoding='utf-8') → str | None

Return the object represented as a str containing the JavaScript object literal.

Parameters:

filename (Path-like) – The name of a file to which the JavaScript object literal should be persisted. Defaults to None
encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

Return type:

str or None

to_json(filename=None, encoding='utf-8')

Generate a JSON string/byte string representation of the object compatible with the Highcharts JavaScript library.

Note

This method will either return a standard str or a bytes object depending on the JSON serialization library you are using. For example, if your environment has orjson, the result will be a bytes representation of the string.

Parameters:

filename (Path-like) – The name of a file to which the JSON string should be persisted. Defaults to None
encoding (str) – The character encoding to apply to the resulting object. Defaults to 'utf-8'.

Returns:

A JSON representation of the object compatible with the Highcharts library.

Return type:

str or bytes

static trim_dict(untrimmed: dict, to_json: bool = False) → dict

Remove keys from untrimmed whose values are None and convert values that have .to_dict() methods.

Parameters:

untrimmed (dict) – The dict whose values may still be None or Python objects.
to_json (bool) – If True, will remove all keys from untrimmed that are not serializable to JSON. Defaults to False.

Returns:

Trimmed dict

Return type:

dict

static trim_iterable(untrimmed, to_json=False)

Convert any EnforcedNullType values in untrimmed to 'null'.

Parameters:

untrimmed (iterable) – The iterable whose members may still be None or Python objects.
to_json (bool) – If True, will remove all members from untrimmed that are not serializable to JSON. Defaults to False.

Return type:

iterable

property accessibility: TypeOptionsAccessibility | None

Accessibility options for a series.

Return type:: TypeOptionsAccessibility or None

property allow_point_select: bool | None

Allow this series’ points to be selected by clicking on the graphic (columns, point markers, pie slices, map areas etc).

The selected points can be handled in JavaScript by point select and unselect events, or collectively by the (JavaScript) getSelectedPoints() function.

And alternative way of selecting points is through dragging.

Defaults to False.

Return type:: bool or None

property animation: AnimationOptions | None

Enable or disable the initial animation when a series is displayed.

The animation can also be set as a configuration object. Please note that this option only applies to the initial animation of the series itself. For other animations, see Chart.animation and the animation parameter under the (JavaScript) API methods. The following properties are supported:

defer: The animation delay time in milliseconds.

duration: The duration of the animation in milliseconds.

easing: Can be a string reference to an easing function set on the Math object or a function.

Warning

Due to poor performance, animation is disabled in old IE browsers for several chart types.

Return type:: AnimationOptions or None

property animation_limit: int | float | Decimal | None

For some series, there is a limit that shuts down initial animation by default when the total number of points in the chart is too high. Defaults to None.

For example, for a column chart and its derivatives, animation does not run if there is more than 250 points totally. To disable this cap, set animation_limit to float("inf") (which represents infinity).

Return type:: numeric or None

property boost_blending: str | None

Sets the color blending in the boost module. Defaults to None.

Return type:: str or None

property boost_threshold: int | None

Set the point threshold for when a series should enter boost mode. Defaults to 5000.

Setting it to e.g. 2000 will cause the series to enter boost mode when there are 2,000 or more points in the series.

To disable boosting on the series, set the boost_threshold to 0. Setting it to 1 will force boosting.

Note

The AreaOptions.crop_threshold() also affects this setting.

When zooming in on a series that has fewer points than the crop_threshold, all points are rendered although outside the visible plot area, and the boost_threshold won’t take effect.

Return type:: int or None

property class_name: str | None

The additional CSS class name to apply to the series’ graphical elements.

Note

This option is additive to the default class names - it does not replace them.

Return type:: str or None

property clip: bool | None

If False, allows the series to be rendered in the entire plot area. If True, constrains where the series can be rendered within the plot area. Defaults to True.

Return type:: bool or None

property color: str | Gradient | Pattern | None

The main color of the series.

In line type series it applies to the line and the point markers unless otherwise specified. In bar type series it applies to the bars unless a color is specified per point. The default value is pulled from the Options.colors() array.

Returns:: The main color applied to the series.
Return type:: str, Gradient, Pattern`, or None

property color_axis: str | int | bool | None

When using dual or multiple color axes, this setting defines which color axis the particular series is connected to. It refers to either the ColorAxis.id() or the index of the axis in the ColorAxis array, with 0 being the first. Set this option to False to prevent a series from connecting to the default color axis.

Defaults to 0.

Return type:: None or str or int or bool

property color_index: int | None

When operating in styled mode, a specific color index to use for the series, so that its graphic representations are given the class name highcharts-color-{n}.

Tip

New in version Highcharts: (JS) v.11

With Highcharts (JS) v.11, using CSS variables of the form --highcharts-color-{n} make changing the color scheme very simple.

Defaults to None.

Return type:: int or None

property color_key: str | None

Determines what data value should be used to calculate point color if AreaOptions.color_axis() is used.

Note

Requires to set min and max if some custom point property is used or if approximation for data grouping is set to 'sum'.

Return type:: str or None

property connect_ends: bool | None

If True, connect the ends of a line series plot across the extremes. Defaults to None.

Warning

Applies to polar charts only.

Return type:: bool or None

property connect_nulls: bool | None

If True, connect a graph line across null points. If False, renders a gap between the points on either side of the null point. Defaults to False.

Return type:: bool or None

property crisp: bool | None

If True, each point or column edge is rounded to its nearest pixel in order to render sharp on screen. Defaults to True.

Hint

In some cases, when there are a lot of densely packed columns, this leads to visible difference in column widths or distance between columns. In these cases, setting crisp to False may look better, even though each column is rendered blurry.

Return type:: bool or None

property crop_threshold: int | None

When the series contains less points than the crop threshold, all points are drawn, even if the points fall outside the visible plot area at the current zoom. Defaults to 300.

The advantage of drawing all points (including markers and columns), is that animation is performed on updates. On the other hand, when the series contains more points than the crop threshold, the series data is cropped to only contain points that fall within the plot area. The advantage of cropping away invisible points is to increase performance on large series.

Return type:: int or None

property cursor: str | None

The style of cursor to use when the user’s mouse hovers over the data series.

Acceptable values are:

'alias'

'all-scroll'

'auto'

'cell'

'col-resize'

'context-menu'

'copy'

'crosshair'

'default'

'e-resize'

'ew-resize'

'grab'

'grabbing'

'help'

'move'

'n-resize'

'ne-resize'

'nesw-resize'

'no-drop'

'none'

'not-allowed'

'ns-resize'

'nw-resize'

'nwse-resize'

'pointer'

'progress'

'row-resize'

's-resize'

'se-resize'

'sw-resize'

'text'

'vertical-text'

'w-resize'

'wait'

'zoom-in'

'zoom-out'

Return type:: str or None

property custom: JavaScriptDict | None

A reserved subspace to store options and values for customized functionality.

Here you can add additional data for your own event callbacks and formatter callbacks.

Return type:: dict or None

property dash_style: str | None

Name of the dash style to use for the graph, or for some series types the outline of each shape.

Accepts one of the following values:

‘Dash’,

‘DashDot’,

‘Dot’,

‘LongDash’,

‘LongDashDot’,

‘LongDashDotDot’,

‘ShortDash’,

‘ShortDashDot’,

‘ShortDashDotDot’,

‘ShortDot’,

‘Solid’

Return type:: str or None

property data: List[SinglePointData] | None

Collection of data that represents the series. Defaults to None.

While the series type returns a collection of SinglePointData instances, it accepts as input three different types of data:

series = PieSeries()
series.data = [0, 5, 3, 5]

A one-dimensional collection of numerical values. Each member of the collection will be interpreted as a y value

A one-dimensional collection of SinglePointData objects.

Return type:: list of SinglePointData or None

property data_labels: DataLabel | List[DataLabel] | None

Options for the series data labels, appearing next to each data point.

Note

To have multiple data labels per data point, you can also supply a collection of DataLabel configuration settings.

Return type:: DataLabel, list of DataLabel, or None

property data_sorting: DataSorting | None

Options for the series data sorting.

Return type:: DataSorting or None

property description: str | None

A description of the series to add to the screen reader information about the series.

Return type:: str or None

property drag_drop: DragDropOptions | None

The draggable-points module allows points to be moved around or modified in the chart.

In addition to the options mentioned under the dragDrop API structure, the module fires three (JavaScript) events:

point.dragStart

point.drag

point.drop

Return type:: DragDropOptions or None

property enable_mouse_tracking: bool | None

If True, enables mouse tracking for the series (used to capture point tooltips, click events on graphs and points, etc.). If False, disables mouse tracking for the series (which can help performance). Defaults to True.

Return type:: bool or None

property events: SeriesEvents | None

General event handlers for the series items.

Note

These event hooks can also be attached to the series at run time using the (JavaScript) Highcharts.addEvent() function.

Return type:: SeriesEvents or None

property find_nearest_point_by: str | None

Determines whether the series should look for the nearest point in both dimensions or just the x-dimension when hovering the series.

If None, defaults to 'xy' for scatter series and 'x' for most other series. If the data has duplicate x-values, it is recommended to set this to 'xy' to allow hovering over all points.

Applies only to series types using nearest neighbor search (not direct hover) for tooltip.

Return type:: str or None

property get_extremes_from_all: bool | None

If True, uses the Y extremes of the total chart width or only the zoomed area when zooming in on parts of the X axis. By default, the Y axis adjusts to the min and max of the visible data.

Warning

Applies to Cartesian series only.

Return type:: bool or None

property id: str | None

An id for the series. Defaults to None.

Hint

This can be used (in JavaScript) after render time to get a pointer to the series object through chart.get().

Return type:: str or None

property include_in_data_export: bool | None

If False, will prevent the data series from being included in any form of data export. Defaults to True.

Return type:: bool or None

property index: int | None

The index for the series in the chart, affecting the internal index in the (JavaScript) chart.series array, the visible Z-index, and the order of the series in the legend. Defaults to None.

Return type:: int or None

property inner_radius: str | int | float | Decimal | None

The inner radius for points in a solid gauge. Can be given as a number (pixels) or percentage string. Defaults to 60.

Return type:: numeric, str, or None

property keys: List[str] | None

An array specifying which option maps to which key in the data point array.

This makes it convenient to work with unstructured data arrays from different sources.

Return type:: list of str, or None

property label: SeriesLabel | None

Series labels are placed as close to the series as possible in a natural way, seeking to avoid other series. The goal of this feature is to make the chart more easily readable, like if a human designer placed the labels in the optimal position.

Note

The series labels currently work with series types having a graph or an area.

Return type:: SeriesLabel or None

property legend_index: int | None

The sequential index for the series in the legend. Defaults to None.

Return type:: int or None

property line_width: int | float | Decimal | None

Pixel width of the graph line. Defaults to 2.

Return type:: numeric or None

property linecap: str | None

The SVG value used for the stroke-linecap and stroke-linejoin of a line graph. Defaults to 'round', which means that lines are rounded in the ends and bends.

Return type:: str or None

property linked_to: str | None

The id of another series to link to.

Hint

The value can be ':previous' to link to the previous series. When two series are linked, only the first one appears in the legend. Toggling the visibility of this also toggles the linked series.

Note

If the master series uses data sorting and linked series does not have its own sorting definition, the linked series will be sorted in the same order as the master one.

Return type:: str or None

property marker: Marker | None

Options for the point markers of line-like series.

Properties like fill_color, line_color and line_width define the visual appearance of the markers. Other series types, like column series, don’t have markers, but have visual options on the series level instead.

Return type:: Marker or None

property name: str | None

The name of the series as shown in the legend, tooltip, etc. Defaults to None.

Return type:: str or None

property negative_color: str | Gradient | Pattern | None

The color for the parts of the graph or points that are below the AreaOptions.threshold().

Note

Zones take precedence over the negative color. Using negative_color is equivalent to applying a zone with value of 0.

Return type:: None, Gradient, Pattern, or str

property on_point: OnPointOptions | None

Options for the Series on point feature, which is currently only supported by pie and sunburst chargs.

Return type:: OnPointOptions or None

property opacity: float | None

Opacity of a series parts: line, fill (e.g. area), and labels.

Return type:: float

property overshoot: int | float | Decimal | None

Allow the dial to overshoot the end of the perimeter axis by this many degrees.

For example, if this option is set to 5 and the gauge axis goes from 0 to 60, a value of 100, or 1000, will show 5 degrees beyond the end of the axis.

Defaults to 0.

Return type:: numeric or None

property point: Point | None

Properties for each single point.

Return type:: Point or None

property point_description_formatter: CallbackFunction | None

Same as for Accessibility.series.description_formatter(), only for an individual series. Overrides the chart-wide configuration.

Return type:: CallbackFunction or None

property point_interval: int | float | Decimal | None

If no x values are given for the points in a series, point_interval defines the interval of the x values. Defaults to 1.

For example, if a series contains one value every decade starting from year 0, set point_interval to 10. In true datetime axes, the point_interval is set in milliseconds.

Hint

point_interval can be also be combined with point_interval_unit to draw irregular time intervals.

Note

If combined with relative_x_value, an x value can be set on each point, and the point_interval is added x times to the point_start setting.

Warning

This options applies to the series data, not the interval of the axis ticks, which is independent.

Return type:: numeric or None

property point_interval_unit: str | None

On datetime series, this allows for setting the point_interval to irregular time units, day, month, and year.

A day is usually the same as 24 hours, but point_interval_unit also takes the DST crossover into consideration when dealing with local time.

Combine this option with point_interval to draw weeks, quarters, 6 month periods, 10 year periods, etc.

Warning

This options applies to the series data, not the interval of the axis ticks, which is independent.

Return type:: str or None

property point_placement: str | int | float | Decimal | None

Used to determine the placement of the point in relation to tick marks on the X axis. Defaults to None, which behaves as undefined in cartesian charts, and "between" in polar charts.

Accepts possible values:

'on' - where the point will not create any padding of the X axis. In a polar column chart this means that the first column points directly north.

"between" - where the columns will be laid out between ticks. This is useful for example for visualising an amount between two points in time or in a certain sector of a polar chart.

a numeric value - where 0 is on the axis value, -0.5 is between this value and the previous, and 0.5 is between this value and the next. Unlike the textual options, numeric point placement options won’t affect axis padding.

Warning

Requires point_range to work. For column series this is computed, but for line-type series it needs to be set.

Note

For the xrange series type and gantt charts, if the Y axis is a category axis, the point_placement applies to the Y axis rather than the (typically datetime) X axis.

Return type:: str or None

property point_start: int | float | Decimal | None

If no x values are given for the points in a series, point_start defines on what value to start. For example, if a series contains one yearly value starting from 1945, set point_start to 1945. Defaults to 0.

Note

If combined with relative_x_value, an x value can be set on each point. The x value from the point options is multiplied by point_interval and added to point_start to produce a modified x value.

Return type:: numeric or None

property radius: str | int | float | Decimal | None

The outer radius for points in a solid gauge. Can be given as a number (pixels) or percentage string. Defaults to 100.

Return type:: numeric, str, or None

property relative_x_value: bool | None

When True, X values in the data set are relative to the current point_start, point_interval, and point_interval_unit settings. This allows compression of the data for datasets with irregular X values. Defaults to False.

The real X values are computed on the formula f(x) = ax + b, where a is the point_interval (optionally with a time unit given by point_interval_unit), and b is the point_start.

Return type:: bool or None

property rounded: bool | None

If True, draws rounded edges on the gauge. Defaults to False.

Return type:: bool or None

property selected: bool | None

If True, the series is selected initially (by default, without user interaction). Defaults to False.

Note

If GenericTypeOptions.show_checkbox() is True, then the checkbox will be checked if selected is True.

Return type:: bool or None

property shadow: bool | ShadowOptions | None

Configuration for the shadow to apply to the tooltip. Defaults to False.

If False, no shadow is applied.

Returns:: The shadow configuration to apply or a boolean setting which hides the shadow or displays the default shadow.
Return type:: bool or ShadowOptions

property show_checkbox: bool | None

If True, a checkbox is displayed next to the legend item to allow selecting the series.

Note

The state of the checkbox is controlled by the GenericTypeOptions.selected() property.

Return type:: bool or None

property show_in_legend: bool | None

Whether to display this particular series or series type in the legend. Standalone series are shown in the legend by default, and linked series are not.

Return type:: bool or None

property skip_keyboard_navigation: bool | None

If True, the accessibility module will skip past this series when executing keyboard navigation.

Return type:: bool or None

property soft_threshold: bool | None

When True, the series will not cause the Y axis to cross the zero plane (or threshold option) unless the data actually crosses the plane. Defaults to True.

For example, if False, a series of 0, 1, 2, 3 will make the Y axis show negative values according to the min_padidng option. If True, the Y axis starts at 0.

Return type:: bool

property sonification: SeriesSonification | None

Sonification configuration for the series type/series.

Return type:: SeriesSonification or None

property stack: str | None

Indicates the “stack” into which the series should be grouped, if the chart groups series into stacks. Defaults to None.

Note

The value can be a string or a numeric value, provided that series in the same stack all have the same value when converted to a string. For ease of ues, Highcharts for Python will attempt to force the conversion of the relevant value to a string.

Return type:: str or None

property stacking: str | None

Whether to stack the values of each series on top of each other. Defaults to None.

Acceptable values are:

None to disable stacking,

"normal" to stack by value or

"percent"

'stream' (for streamgraph series type only)

'overlap' (for waterfall series type only)

Note

When stacking is enabled, data must be sorted in ascending X order.

Return type:: str or None

property states: States | None

Configuration for state-specific configuration to apply to the data series.

Return type:: States or None

property step: str | None

Whether to apply steps to the line. Defaults to None.

Possible values are:

None

'left'

'center'

'right'

Return type:: str or None

property sticky_tracking: bool | None

Sticky tracking of mouse events.

When True, the (JavaScript) mouseOut event on a series is not triggered until the mouse moves over another series, or out of the plot area.

When False, the (JavaScript) mouseOut event on a series is triggered when the mouse leaves the area around the series’ graph or markers. This also implies the tooltip when not shared.

When False and PlotOptions.tooltip.shared() is also False, the tooltip will be hidden when moving the mouse between series.

Defaults to True for line and area type series, but to False for columns, pies, etc.

Note

The boost module will force this option because of technical limitations.

Return type:: bool or None

property threshold: int | float | Decimal | EnforcedNullType | None

The Y axis value to serve as the base for the columns, for distinguishing between values above and below a threshold. Defaults to 0.

If EnforcedNullType, the columns extend from the padding Y axis minimum.

Return type:: numeric or EnforcedNullType or None

property tooltip: Tooltip | None

A configuration object for the tooltip rendering of each single series. Properties are inherited from tooltip, but only the following properties can be defined on a series level.

Return type:: Tooltip or None

property turbo_threshold: int | None

When a series contains a data array longer than this value, only one dimensional arrays of numbers, or two dimensional arrays with x and y values are allowed. Also, only the first point is tested, and the rest are assumed to be the same format. This saves expensive data checking and indexing in long series. Set it to 0 or None to disable.

Defaults to 1000.

Note

In boost mode, turbo threshold is forced. Only array of numbers or two dimensional arrays are allowed.

Return type:: int or None

property type: str

Indicates the type of series that is represented by this instance.

Warning

This proprety is read-only!

Return type:: str

property visible: bool | None

If True, the series is initially visible. If False, the series is hidden by default. Defaults to True.

Return type:: bool or None

property x_axis: str | int | None

When using multiple X-axes, this setting determines on which axis the series should be drawn. Its value should be either a numerical index position in the Options.x_axis() array (starting at 0), or a str indicating the id of the axis to which the series should be connected. Defaults to None, which behaves as if the value were set to 0.

Return type:: str, int, or None

property y_axis: str | int | None

When using multiple Y-axes, this setting determines on which axis the series should be drawn. Its value should be either a numerical index position in the Options.y_axis() array (starting at 0), or a str indicating the id of the axis to which the series should be connected. Defaults to None, which behaves as if the value were set to 0.

Return type:: str, int, or None

property z_index: int | float | Decimal | None

The visual z-index of the series. Defaults to None.

Return type:: numeric or None

property zone_axis: str | None

Defines the Axis on which the zones are applied. Defaults to 'y'.

Return type:: str or None

property zones: List[Zone] | None

An array defining zones within a series. Defaults to None.

Zones can be applied to the X axis, Y axis or Z axis for bubbles, according to the zone_axis setting.

Warning

The zone definitions have to be in ascending order regarding to the value.

Return type:: None or list of Zone instances

.gauge

class: GaugeSeries

class: SolidGaugeSeries

`.gauge`

class: `GaugeSeries`

class: `SolidGaugeSeries`