`.item`

class: `ItemOptions`

class ItemOptions(**kwargs)[source]

General options to apply to all Item series types.

An item chart is an infographic chart where a number of items are laid out in either a rectangular or circular pattern. It can be used to visualize counts within a group, or for the circular pattern, typically a parliament.

The circular layout has much in common with a pie chart. Many of the item series options, like center, size and data label positioning, are inherited from the PlotOptions.pie() series and don’t apply for rectangular layouts.

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_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

get_required_modules(include_extension=False) → List[str]

Return the list of URLs from which the Highcharts JavaScript modules needed to render the chart can be retrieved.

Parameters:: include_extension (bool) – if True, will return script names with the '.js' extension included. Defaults to False.
Return type:: list of str

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', careful_validation=False) → 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'.
careful_validation – if True, will carefully validate JavaScript values

along the way using the esprima-python library. Defaults to False.

Warning

Setting this value to True will significantly degrade serialization performance, though it may prove useful for debugging purposes.

Return type:: str or None

to_json(filename=None, encoding='utf-8', for_export: bool = False)

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'.
for_export (bool) – If True, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults to False.

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, context: str = None, for_export: 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.
context (str or None) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults to None.
for_export (bool) – If True, indicates that the method is being run to produce a JSON for consumption by the export server. Defaults to False.

Returns:

Trimmed dict

Return type:

dict

static trim_iterable(untrimmed, to_json=False, context: str = None, for_export: bool = 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.
context (str or None) – If provided, will inform the method of the context in which it is being run which may inform special handling cases (e.g. where empty strings may be important / allowable). Defaults to None.
for_export (bool) – If True, indicates that the method is being run to produce a JSON for consumption by the export server. 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: bool | 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 border_color: str | Gradient | Pattern | None

The color of the border surrounding each slice. When None, the border takes the same color as the slice fill. This can be used together with a border_width to fill drawing gaps created by antialiazing artefacts in borderless pies. Defaults to '#ffffff'.

Return type:: str or None

New in version Highcharts: Core for Python v.1.1.0 / Highcharts Core (JS) v.11.0.0

The corner radius of the border surrounding each slice. Defaults to 3.

Note

A numerical value signifies the value is expressed in pixels. A percentage string like 50% signifies a size relative to the radius and the inner radius.

Return type:: numeric, str, BorderRadius or None

property border_width: int | float | Decimal | None

The width of the border surrounding each slice. Defaults to 1.

When setting the border width to 0, there may be small gaps between the slices due to SVG antialiasing artefacts. To work around this, keep the border width at 0.5 or 1, but set the border_color to None instead.

Return type:: numeric or None

The center of the pie chart relative to the plot area.

Can be percentages or pixel values. The default behaviour if None is to center the pie so that all slices and data labels are within the plot area. As a consequence, the pie may actually jump around in a chart with dynamic values, as the data labels move. In that case, the center should be explicitly set, for example to ["50%", "50%"].

Defaults to ['50%', '50%'].

Return type:: None or list of numeric or str values

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}.

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 PieOptions.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 colors: List[str | Gradient | Pattern] | None

A series-specific or series type-specific color set to apply instead of the global colors when ArcDiagramOptions.color_by_point() is True.

Return type:: list of str, Gradient, or Pattern 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_labels: PieDataLabel | List[PieDataLabel] | 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:: PieDataLabel, list of PieDataLabel, or None

property depth: int | float | Decimal | None

The thickness of a 3D pie. Defaults to 0.

Return type:: numeric 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 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 end_angle: int | float | Decimal | None

The end angle of the pie in degrees where 0 is top and 90 is right. Defaults to None, which is equivalent to start_angle plus 360.

Return type:: numeric 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 fill_color: str | Gradient | Pattern | None

If the total sum of the pie’s values is 0, the series is represented as an empty circle . The fill_color setting defines the color of that circle. Use PieOptions.border_width() to set the border thickness.

Defaults to None.

Return type:: None, Gradient, or Pattern

property ignore_hidden_point: bool | None

If True, the series shall be redrawn as if the hidden points were null. If False, hidden points will not be displayed but the slice will still be drawn as a gap in the pie.

Defaults to True.

Return type:: bool 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 inner_size: str | int | None

In circular view, the size of the inner diameter of the circle. Defaults to 40%. Can be a percentage or pixel value.

Note

Percentages are relative to the outer perimeter. Pixel values are given as integers.

Warning

If ItemOptions.rows() is set, this value will be overridden by the rows setting.

Return type:: str, int, or None

property item_padding: int | float | Decimal | None

The padding between the items, given in relative size where the size of the item itself is 1. Defaults to 0.1.

Return type:: numeric 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 layout: str | None

The layout of the items in rectangular view. Defaults to 'vertical'.

Accepts:

'horizontal'

'vertical'

Return type:: str or None

property legend_symbol: str | None

The type of legend symbol to render for the series. Accepts either 'lineMarker', 'areaMarker', or 'rectangle'. Defaults to 'rectangle'.

Return type:: str

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 min_size: int | float | Decimal | str | None

The minimum size for a pie in response to auto margins, expressed in pixels or percentages. Defaults to 80.

Note

The pie will try to shrink to make room for data labels in side the plot area, but only to this size.

Return type:: str, int, or None

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 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 rows: int | None

The number of rows to display in the rectangular or circular view. Defaults to None.

Note

If the ItemOptions.inner_size() is set, it will be overridden by the rows setting.

Return type:: int 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 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 size: str | int | None

The diameter of the pie relative to the plot area, expressed as a percentage or pixel value given as an integer.

If None, scales the pie to the plot area and gives room for data labels within the plot area.

Note

PieOptions.sliced_offset() is also included in the default size calculation. As a consequence, the size of the pie may vary when points are updated and data labels more around. In that case it is best to set a fixed value, for example "75%".

Return type:: str, int, 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 sliced_offset: int | float | Decimal | None

If a point is sliced, moved out from the center, how many pixels should it be moved? Defaults to 10.

Return type:: numeric or None

property sonification: SeriesSonification | None

Sonification configuration for the series type/series.

Return type:: SeriesSonification or None

property start_angle: int | float | Decimal | None

The start angle of the dependency wheel, in degrees where 0 is up. Defaults to 0.

Return type:: numeric or None

property states: States | None

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

Return type:: States 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 thickness: int | None

Thickness describing the ring size for a donut type chart, overriding PieOptions.inner_size(). Defaults to None.

Return type:: int 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

.item

class: ItemOptions

`.item`

class: `ItemOptions`