.chart

---

class: Chart

class Chart(**kwargs)

Python representation of a Highcharts Chart object.

Class Inheritance

add_series(*series)

Adds series to the Chart.options.series property.

Parameters:

series (one or more SeriesBase or coercable) – One or more series instances (descended from SeriesBase) or an instance (e.g. dict, str, etc.) coercable to one

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

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

Parameters:

• other (Chart) – The target chart to which the properties of this chart should be copied. If None, will create a new chart 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.

• preserve_data (bool) – If True, will preserve the data values in any series contained in other and the configuration of the options.data property, but will still copy other properties as applicable. If False, will overwrite data in other with data from 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

display(global_options=None)

Display the chart in Jupyter Labs or Jupyter Notebooks.

Raises:

HighchartsDependencyError – if ipython is not available in the runtime environment

download_chart(format='png', scale=1, width=None, filename=None, auth_user=None, auth_password=None, timeout=0.5, server_instance=None, **kwargs)

Export a downloaded form of the chart using a Highcharts Export Server.

Parameters:

• filename (Path-like or None) – The name of the file where the exported chart should (optionally) be persisted. Defaults to None.

• auth_user (str or None) – The username to use to authenticate against the Export Server, using basic authentication. Defaults to None.

• auth_password (str or None) – The password to use to authenticate against the Export Server (using basic authentication). Defaults to None.

• timeout (numeric or None) – The number of seconds to wait before issuing a timeout error. The timeout check is passed if bytes have been received on the socket in less than the timeout value. Defaults to 0.5.

• server_instance (ExportServer or None) – Provide an already-configured ExportServer instance to use to programmatically produce the exported chart. Defaults to None, which causes Highcharts for Python to instantiate a new ExportServer instance.

Note

All other keyword arguments are as per the ExportServer constructor.

Returns:

The exported chart image, either as a bytes binary object or as a base-64 encoded string (depending on the use_base64 keyword argument).

Return type:

bytes or str

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

Create a new Chart instance with data populated from a CSV string or file.

Note

For an example LineSeries, the minimum code required would be:

my_chart = Chart.from_csv('some-csv-file.csv',
                          property_column_map = {
                              'x': 0,
                              'y': 3,
                              'id': 'id'
                          },
                          series_type = 'line')

As the example above shows, data is loaded into the my_chart 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.

• series_type (str) – Indicates the series type that should be created from the CSV data.

• 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 or None) –

  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.

• options_kwargs (dict or None) –

  An optional dict containing keyword arguments that should be used when instantiating the HighchartsOptions instance. Defaults to None.

  Warning

  If options_kwargs contains a series key, the series value will be overwritten. The series value will be created from the CSV file instead.

• chart_kwargs (dict or None) –

  An optional dict containing keyword arguments that should be used when instantiating the Chart instance. Defaults to None.

  Warning

  If chart_kwargs contains an options key, options will be overwritten. The options value will be created from the options_kwargs and 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'.

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

• is_maps_chart (bool) – If True, indicates that the chart should be instantiated as a Highcharts Stock for Python chart. Defaults to False.

Returns:

A Chart instance with its data populated from the CSV data.

Return type:

Chart

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_geopandas(gdf, property_map, series_type, series_kwargs=None, options_kwargs=None, chart_kwargs=None)

Create a Chart instance whose data is populated from a geopandas GeoDataFrame.

Parameters:

• gdf (GeoDataFrame) – The GeoDataFrame 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 gdf. The keys in the dict should correspond to properties in the data point class, while the value should indicate the label for the GeoDataFrame column.

• series_type (str) – Indicates the series type that should be created from the data in gdf.

• 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 gdf instead.

• options_kwargs (dict or None) –

  An optional dict containing keyword arguments that should be used when instantiating the HighchartsOptions instance. Defaults to None.

  Warning

  If options_kwargs contains a series key, the series value will be overwritten. The series value will be created from the data in gdf.

• chart_kwargs (dict or None) –

  An optional dict containing keyword arguments that should be used when instantiating the Chart instance. Defaults to None.

  Warning

  If chart_kwargs contains an options key, options will be overwritten. The options value will be created from the options_kwargs and the data in gdf instead.

Returns:

A Chart instance with its data populated from the data in gdf.

Return type:

Chart

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_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_map_data(map_data, options_kwargs=None, chart_kwargs=None)

Create a Chart instance from a MapData or AsyncMapData object.

Parameters:

• map_data (MapData or AsyncMapData or None) –

  The map geometries to set. Accepts:

  • MapData

  • AsyncMapData

  • VariableName

  • GeoJSONBase or descendant

  • Topology

  • a str URL, which will be coerced to AsyncMapData

• options_kwargs (dict or None) –

  An optional dict containing keyword arguments that should be used when instanting the options for the Chart instance. Defaults to None

  Warning

  If options_kwargs contains a chart.map setting, that value will be overwritten by the contents of map_data.

• chart_kwargs (dict or None) –

  An optional dict containing keyword arguments that should be used when instantiating the instance. Defaults to None.

  Warning

  If chart_kwargs contains an options setting, that value will be overwritten by the options implied by options_kwargs

Returns:

The Chart instance

Return type:

Chart

classmethod from_options(options, chart_kwargs=None)

Create a Chart instance from a HighchartsOptions or HighchartsMapsOptions object.

Parameters:

• options (HighchartsOptions or related or coercable) – The configuration options to use to instantiate the chart.

• chart_kwargs (dict or None) –

  An optional dict containing keyword arguments that should be used when instantiating the instance. Defaults to None.

  Warning

  If chart_kwargs contains an options key, options will be overwritten by the contents of options.

Returns:

The Chart instance

Return type:

Chart

classmethod from_pandas(df, property_map, series_type, series_kwargs=None, options_kwargs=None, chart_kwargs=None)

Create a Chart instance whose data 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_type (str) – Indicates the series type that should be created from the data in df.

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

• options_kwargs (dict or None) –

  An optional dict containing keyword arguments that should be used when instantiating the HighchartsOptions instance. Defaults to None.

  Warning

  If options_kwargs contains a series key, the series value will be overwritten. The series value will be created from the data in df.

• chart_kwargs (dict or None) –

  An optional dict containing keyword arguments that should be used when instantiating the Chart instance. Defaults to None.

  Warning

  If chart_kwargs contains an options key, options will be overwritten. The options value will be created from the options_kwargs and the data in df instead.

Returns:

A Chart instance with its data populated from the data in df.

Return type:

Chart

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_type, series_kwargs=None, options_kwargs=None, chart_kwargs=None)

Create a Chart instance whose data 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_type (str) – Indicates the series type that should be created from the data in df.

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

• options_kwargs (dict or None) –

  An optional dict containing keyword arguments that should be used when instantiating the HighchartsOptions instance. Defaults to None.

  Warning

  If options_kwargs contains a series key, the series value will be overwritten. The series value will be created from the data in df.

• chart_kwargs (dict or None) –

  An optional dict containing keyword arguments that should be used when instantiating the Chart instance. Defaults to None.

  Warning

  If chart_kwargs contains an options key, options will be overwritten. The options value will be created from the options_kwargs and the data in df instead.

Returns:

A Chart instance with its data populated from the data in df.

Return type:

Chart

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

classmethod from_series(*series, kwargs=None)

Creates a new Chart instance populated with series.

Parameters:

• series (one or more SeriesBase or IndicatorSeriesBase coercable) – One or more series instances (descended from SeriesBase) or an instance (e.g. dict, str, etc.) coercable to one

• kwargs (dict) –

  Other properties to use as keyword arguments for the instance to be created.

  Warning

  If kwargs sets the options.series property, that setting will be overridden by the contents of series.

Returns:

A new Chart instance

Return type:

Chart

set_custom_projection(projection)

Applies a custom map projection to the chart.

Parameters:

projection (CustomProjection) – The custom projection definition to apply.

See also

• Using Highcharts Maps for Python > Using Custom Projections

set_map_data(map_data)

Sets the default map geometries for the chart.

Parameters:

map_data (MapData or AsyncMapData or None) –

The map geometries to set. Accepts:

• MapData

• AsyncMapData

• VariableName

• GeoJSONBase or descendant

• Topology

• a str URL, which will be coerced to AsyncMapData

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

Note

If variable_name is set, will render a string as a new JavaScript instance invocation in the (pseudo-code) form:

new VARIABLE_NAME = new Chart(...);

If variable_name is not set, will simply return the new Chart(...) portion in the string.

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

update_series(*series, add_if_unmatched=False)

Replace existing series with the new versions supplied in series, matching them based on their .id property.

Parameters:

• series (one or more SeriesBase or coercable) – One or more series instances (descended from SeriesBase) or an instance (e.g. dict, str, etc.) coercable to one

• add_if_unmatched (bool) – If True, will add a series that does not have a match. If False, will raise a HighchartsMissingSeriesError if a series does not have a match on the chart. Defaults to False.

property callback: CallbackFunction | None

A (JavaScript) function that is run when the chart has loaded and all external images have been loaded. Defaults to None.

Note

Setting this proprety is equivalent to setting a value for ChartOptions.events.load

Return type:

CallbackFunction or None

property container: str | None

The id of the <div> element in which your Highcharts chart should be rendered. Defaults to None.

Return type:

str or None

property is_async: bool

Read-only property which indicates whether the data visualization should be rendered using asynchronous logic.

Note

This property will only return True if one or more series rely on AsyncMapData

Return type:

bool

property is_maps_chart: bool

If True, indicates that the chart should be rendered as a Highcharts Maps chart. If False, the chart will be rendered using the standard Highcharts JS constructor. Defaults to False.

Return type:

bool

property options: HighchartsOptions | HighchartsMapsOptions | None

The Python representation of the Highcharts Maps options configuration object Defaults to None.

Return type:

HighchartsOptions or HighchartsMapsOptions or None

property uses_custom_projection: bool

Read-only property which indicates whether the map visualization applies a custom projection.

Note

This property will only return True if the options.map_views.projection.custom property is set.

Return type:

bool

property variable_name: str | None

The name given to the (JavaScript) variable to which the (JavaScript) Chart instance wil be assigned. Defaults to None.

Note

When the Chart object is converted to JavaScript code, the (JavaScript) chart instance is assigned to a variable in your JavaScript code. In the example code below, the Chart instance is assigned to a variable_name of chart1:

var chart1 = Highcharts.Chart('myTargetDiv', {});

Warning

If None, when converted to a JavaScript literal, the Chart instance will simply not be assigned to a variable.

Return type:

str or None