.clusters

class: ClusterOptions

class ClusterOptions(**kwargs)[source]

Options for marker clusters, the concept of sampling the data values into larger blocks in order to ease readability and increase performance of the JavaScript charts.

Warning

The marker clusters module does not work with boost and draggable-points modules.

Note

The marker clusters feature requires the marker-clusters.js file to be loaded, found in the modules directory of the download package, or online at code.highcharts.com/modules/marker-clusters.js.

Class Inheritance
Inheritance diagram of ClusterOptions

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 allow_overlap: bool | None

If True, clusters are allowed to overlap. Otherwise, overlapping is prevented. Defaults to True.

Warning

Preventing overlapping only works if layout_algorithm.type is set to 'grid'.

Returns:

Flag indicating whether to allow clusters to overlap.

Return type:

bool or None

property animation: AnimationOptions | None

Options for the cluster marker animation.

Return type:

AnimationOptions or None

property data_labels: DataLabel | None

Options for the cluster data labels.

Return type:

DataLabel or None

property drill_to_cluster: bool | None

If True, zoom the plot area to the cluster points range when a cluster is clicked. Defaults to True.

Return type:

bool or None

property enabled: bool | None

If True, enables the marker-clusters module. Defaults to False.

Return type:

bool or None

property events: ClusterEvents | None

General event handlers for marker clusters.

Return type:

SeriesEvents or None

property layout_algorithm: VectorLayoutAlgorithm | None

Options for the layout algorithm to apply to the Vector chart.

Return type:

VectorLayoutAlgorithm 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 minimum_cluster_size: int | None

The minimum number of points to be combined into a cluster. Defaults to 2.

Note

This value has to be greater or equal to 2.

Return type:

int or None

property states: States | None

Configuration for state-specific configuration to apply to all clusters.

Return type:

States or None

property zones: List[ClusterZone] | None

An array defining zones within marker clusters.

Return type:

None or list of ClusterZone instances

class: VectorLayoutAlgorithm

class VectorLayoutAlgorithm(**kwargs)[source]

Options for the layout algorithm to apply to the Vector chart.

Class Inheritance
Inheritance diagram of VectorLayoutAlgorithm

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

When VectorLayoutAlgorithm.type() is set to 'kmeans', distance is a maximum distance between point and cluster center so that this point will be inside the cluster. Defaults to 40.

The distance is either a number expressed in pixels or a percentage defining a percentage of the plot area width.

Return type:

str, numeric, or None

property grid_size: int | float | Decimal | str | None

When VectorLayoutAlgorithm.type() is set to 'grid', grid_size is is a size of a grid square element. Defaults to 50.

The grid_size is either a number expressed in pixels or a percentage defining a percentage of the plot area width.

Return type:

str, numeric, or None

property iterations: int | None

When VectorLayoutAlgorithm.type() is set to 'kmeans', the iterations indicates the number of times that the algorithm will be repeated to find cluster positions. Defaults to None.

Return type:

int or None

property kmeans_threshold: int | None

When VectorLayoutAlgorithm.type() is set to None and the number of visible points is less than or equal to kmeans_threshold, the 'kmeans' algorithm is used by default to find clusters. When the number of visible points exceeds the kmeans_threshold, the 'grid' algorithm is used. Defaults to 100.

Hint

This threshold is a powerful tool to ensure good performance on large datasets and better cluster arrangemnet after zoom.

Return type:

int or None

property type: str | None

Type of algorithm to use to combine points into a cluster. Defaults to None.

There are three available algorithms:

  • 'grid' - grid-based clustering technique. Points are assigned to squares of set size depending on their position on the plot area. Points inside the grid square are combined into a cluster. The grid size can be controlled by VectorLayoutAlgorithm.grid_size() (grid size changes at certain zoom levels).

  • 'kmeans' - based on K-Means clustering technique. In the first step, points are divided using the grid method (applying VectorLayoutAlgorithm.distance() as the grid size) to find the initial amount of clusters. Next, each point is classified by computing the distance between each cluster center and that point. When the closest cluster distance is lower than VectorLayoutAlgorithm.distance(), the point is added to this cluster otherwise is classified as noise. The algorithm is repeated until each cluster center does not change its previous position more than one pixel. This technique is more accurate but also more time consuming than the 'grid' algorithm, especially for big datasets.

  • 'optimizedKmeans' - based on K-Means clustering technique. This algorithm uses k-means algorithm only on the chart initialization or when chart extremes have greater range than on initialization. When a chart is redrawn the algorithm checks only clustered points distance from the cluster center and rebuilds it when the point is spaced enough to be outside the cluster. It provides a performance improvement and more stable clusters position so that it can be used rather on small and sparse datasets.

When None, the algorithm applied depends on VectorLayoutAlgorithm.kmeans_threshold() such that if there are more visible points than the kmeans_threshold the 'grid' algorithm is applied. If fewer, then 'kmeans' is applied.

A custom clustering algorithm can be applied by setting type to a JavaScript callback function. This function takes an array of processedXData, processedYData, processedXData indexes, and VectorLayoutAlgorithm options as arguments and should return an object with grouped data.

A custom algorithm should return an object similar to:

{
 clusterId1: [{
     x: 573,
     y: 285,
     index: 1 // point index in the data array
 }, {
     x: 521,
     y: 197,
     index: 2
 }],
 clusterId2: [{
     ...
 }]
 ...
}

Where clusterId* (in the example above - a unique id of a cluster or noise) is an array of points belonging to a cluster. If the array has only one point or fewer points than set in Cluster.minimum_cluster_size, it won’t be combined into a cluster.