.boost

class: Boost

class Boost(**kwargs)[source]

Options for the Boost module.

The Boost module allows certain series types to be rendered by WebGL instead of the default SVG. This allows hundreds of thousands of data points to be rendered in milliseconds. In addition to the WebGL rendering it saves time by skipping processing and inspection of the data wherever possible. This introduces some limitations to what features are available in boost mode. See the docs for details.

Note

In addition to the global HighchartOptions.boost() property, each series has a Series.boost_threshold() that defines when the boost should kick in.

Class Inheritance
Inheritance diagram of Boost

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

If True, the whole chart will be boosted if one of the series crosses its threshold and all the series can be boosted. Defaults to True.

Returns:

Flag indicating whether the entire chart can be boosted in response to one series being boosted.

Return type:

class:bool <python:bool> or None

property debug: BoostDebug | None

Debugging options for boost. Useful for benchmarking, and general timing.

Return type:

BoostDebug or None

property enabled: bool | None

If True, boost is enabled on the chart. If False, boost is disabled. Defaults to True.

Returns:

Flag indicating whether boost is enabled for the chart.

Return type:

bool or None

property pixel_ratio: int | None

The pixel ratio for the WebGL content. Defaults to 1.

If 0, the window.devicePixelRatio is used. This ensures sharp graphics on high DPI displays like Apple’s Retina, as well as when a page is zoomed.

Note

The default is left at 1 for now, as this is a new feature that has the potential to break existing setups. Over time, when it has been battle tested, the intention is to set it to 0 by default.

Hint

Another use case for this option is to set it to 2 in order to make exported and upscaled charts render sharp.

Warning

One limitation when using the pixel_ratio is that the line width of graphs is scaled down. Since the Boost module currently can only render 1px line widths, it is scaled down to a thin 0.5 pixels on a Retina display.

Return type:

int or None

property series_threshold: int | None

Set the series threshold for when the boost should kick in globally. Defaults to 50.

Setting to e.g. 20 will cause the whole chart to enter boost mode if there are 20 or more series active. When the chart is in boost mode, every series in it will be rendered to a common canvas. This offers a significant speed improvment in charts with a very high amount of series.

Return type:

int or None

property use_gpu_translations: bool | None

If True, enables GPU translations. GPU translations are faster than doing the translation in JavaScript. Defaults to False.

Warning

This option may cause rendering issues with certain datasets. Namely, if your dataset has large numbers with small increments (such as timestamps), it won’t work correctly. This is due to floating point precission.

Returns:

Flag indicating whether to use GPU translations.

Return type:

bool or None <python:None.

property use_preallocated: bool | None

If True, enables the pre-allocation of vertex buffers. Defaults to False.

Enabling this will make it so that the binary data arrays required for storing the series data will be allocated prior to transforming the data to a WebGL-compatible format.

Warning

Enabling this feature saves a copy operation on the order of O(n) and so is significantly more performant. However, this is currently an experimental option, and may cause visual artifacts with some datasets.

As such, care should be taken when using this setting to make sure that it doesn’t cause any rendering glitches with the given use-case.

Returns:

Flag indicating whether pre-allocation of vertex buffers is enabled.

Return type:

bool or None

class: BoostDebug

class BoostDebug(**kwargs)[source]

Debugging options for boost. Useful for benchmarking, and general timing.

Class Inheritance
Inheritance diagram of BoostDebug

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

When True, the number of points skipped in series processing is outputted. Defaults to False.

Points are skipped if they are closer than 1 pixel from each other.

Returns:

Flag indicating whether the skip summary will be shown.

Return type:

bool or None

property time_buffer_copy: bool | None

When True, the time it takes for the SVG buffer copy to complete is outputted. Defaults to False.

Returns:

Flag indicating whether the buffer copy timing will be shown.

Return type:

bool or None

property time_kd_tree: bool | None

When True, the time spent building the k-d tree used for markers, etc. will be rendered. Defaults to False.

Note

Note that the k-d tree is built asynchronously, and runs post-rendering. Thus, it does not affect the performance of the rendering itself.

Returns:

Flag indicating whether the KD tree timing will be shown.

Return type:

bool or None

property time_rendering: bool | None

When True, the time spent on actual rendering is outputted to the console. Defaults to False.

Returns:

Flag indicating whether the rendering time will be shown.

Return type:

bool or None

property time_series_processing: bool | None

When True, the time spent on transforming the series data to vertex buffers is outputted. Defaults to False.

Returns:

Flag indicating whether the series processing time will be shown.

Return type:

bool or None

property time_setup: bool | None

When True, the te time spent on setting up the WebGL context, creating shaders, and textures is outputted. Defaults to False.

Returns:

Flag indicating whether the setup time will be shown.

Return type:

bool or None