.data

class: Data

class Data(**kwargs)[source]

The data property provides a simplified interface for adding data to a chart from sources like CVS, HTML tables, or grid views. See also the tutorial article on the Data module.

Warning

It requires the modules/data.js file to be loaded in the browser / client.

Warning

Please note that the default way of adding data in Highcharts, without the need of a module, is through the series.data property.

Class Inheritance
Inheritance diagram of Data

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

classmethod from_pandas(as_df, represent_as='csv', data_kwargs=None, pandas_kwargs=None)[source]

Create a Data instance from a Pandas DataFrame <pandas:DataFrame.

Parameters:

  • as_df (DataFrame) – The DataFrame from which to create the Data instance.

  • represent_as (str) – The format to which as_df should be serialized. Accepts 'csv' or 'html'. Defaults to 'csv'.

  • data_kwargs (dict) – Additional keyword arguments to pass to the Data constructor (__init__()) method. Defaults to None.

  • pandas_kwargs (dict) – Keyword arguments to pass to the Pandas DataFrame.to_csv() or DataFrame.to_html() methods. Defaults to None.

Note

To prevent unexpected behavior, if represent_as is set to 'csv', the Data.table() property will be set to None. If represent_as is set to 'html', the Data.csv() property will be set to None.

Returns:

A Data instance.

classmethod from_pyspark(as_df, data_kwargs=None, pyspark_kwargs=None, consolidation='repartition')[source]

Create a Data instance from a PySpark DataFrame.

Warning

If you are using PySpark, you might be working with extremely large datasets (proverbial “big data”). Are you sure you want to be visualizing datasets of such size? If so, you should be aware that Highcharts for Python tries to store the dataset in the Python environment’s memory - not on disk.

If you need to read large datasets from disk, using the Data.from_pyspark() is not recommended for this reason.

Parameters:

  • as_df (pyspark.sql.DataFrame) – The DataFrame from which to create the Data instance.

  • data_kwargs (dict) –

    Additional keyword arguments to pass to the Data constructor (__init__()) method. Defaults to None.

    Warning

    The Data.csv() and Data.table() properties will be overwritten by Highcharts for Python if specified, so don’t bother.

  • pyspark_kwargs (dict) –

    Keyword arguments to pass to the Pyspark DataFrame.write().csv() method. Defaults to None.

    Warning

    The path and mode arguments will be overwritten by Highcharts for Python if specified, so don’t bother.

  • consolidation –

    If 'repartition', will repartition your PySpark DataFrame into a single unpartitioned table prior to the generation of a CSV dataset. If 'coalesce', will coalesce your PySpark DataFrame into a single unpartitioned table prior to the generation of a CSV dataset. If None, will not apply any consolidation to the DataFrame. Defaults to 'coalesce'.

    Hint

    Setting this value to 'coalesce' is particularly useful if you are working on your DataFrame in multiple Spark nodes to prevent loss of data.

    Setting this value to None may provide a boost to performance, however use with caution as it may lead to unexpected data loss or errors if using multiple Spark nodes.

Returns:

A Data instance.

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

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, context: str = None) → 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.

Returns:

Trimmed dict

Return type:

dict

static trim_iterable(untrimmed, to_json=False, context: str = None)

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.

Return type:

iterable

property before_parse: CallbackFunction | None

A JavaScript callback function that is used to modify the CSV data before it is parsed. The function should return a modified version of the CSV string. Defaults to None.

Return type:

CallbackFunction or None

property column_types: List[str] | None

The data types for each column in the related CSV data.

This property expects an iterable of str values, where each item in the iterable corresponds to a column in the underlying CSV data. The type specified for each column may be one of the following values:

  • 'string'

  • 'number'

  • 'float'

  • 'date'

Defaults to None.

Returns:

The data types for each column in the related CSV data.

Return type:

list of str or None

property columns: List[List[int | str | float | Decimal | None | EnforcedNullType]] | None

The data itself represented in a tabular form. Expects an iterable of iterables, where each second-level iterable represents a column of data. Defaults to None.

my_data = Data()
my_data.columns = [
  [None, 'Apples', 'Pears', 'Oranges'], # categories
  ['Ola', 1, 4, 3], # first series for "Ola"
  ['Kari', 5, 4, 2] # second series for "Kari"
]

Note

Each cell in the second-level iterable can either be a str, numeric value, None, or EnforcedNullType.

Hint

Provided that Data.switch_rows_and_columns() is not set, the columns will be interpreted as series.

Return type:

None or list of list instances with str, numeric, None, or EnforcedNullType members

property columns_url

A URL to a remote JSON dataset, structured as a column array. Defaults to None.

Note

Will be fetched when the chart is created using Ajax.

Return type:

str or None

property complete: CallbackFunction | None

The JavaScript callback function that is evaluated when the data has finished loading (optionally from an external source) and been parsed. The first argument passed is a finished chart options object, containing the series. These options can be extended with additional options and passed directly to the chart constructor. Defaults to None.

Return type:

CallbackFunction or None

property csv: str | None

A comma-delimited string to be parsed. Defaults to None.

See also

The object has closely-related properties that determine which part of the CSV string should be used when constructing the chart and to configure how the CSV string should be parsed. In particular, please review:

Warning

The built-in CSV parser does not support all flavours of CSV, so in some cases it may be necessary to use an external CSV parser. See this example of parsing a CSV through the MIT-licensed Papa Parse library.

Return type:

str or None

property csv_url

A URL to a remote CSV dataset. Defaults to None.

Note

Will be fetched when the chart is created using Ajax.

Return type:

str or None

property data_refresh_rate: int | float | Decimal | None

The number of seconds between each poll of data from a remote source configured using either Data.columns_url(), Data.csv_url(), Data.rows_url(), or Data.google_spreadsheet_key(). Defaults to 1.

Warning

Cannot be set to less than 1.

Note

For polling to be enabled, Data.enable_polling() must be True.

Return type:

numeric or None

property date_format: str | None

Indicates the format string to use to parse date values. If None, defaults to a best-guess based on what format gives valid and ordered dates. Defaults to None.

Valid options include:

  • 'YYYY/mm/dd'

  • 'dd/mm/YYYY'

  • 'mm/dd/YYYY'

  • 'dd/mm/YY'

  • 'mm/dd/YY'

Return type:

str or None

property decimal_point: str | None

The decimal point used when parsing number values. Defaults to '.' if None.

Note

If both decimal_point and Data.delimiter() are set to None, the parser will attempt to deduce the decimal point automatically.

Return type:

str

property enable_polling: bool | None

If True, automatically re-fetches remote datasets every n seconds (as per Data.data_refresh_rate()). Defaults to False.

Note

This flag only has an impact if remote datasets are in use, as specified by any one of:

Return type:

bool or None

property end_column: int | None

In tabular input data, the last column (indexed by 0) to use. If None, defaults to the last column that contains data.

Return type:

int or None

property end_row: int | None

In tabular input data, the last row (indexed by 0) to use. If None, defaults to the last row that contains data.

Return type:

int or None

property first_row_as_names: bool | None

If True, use the first row of data as series names. Defaults to True.

Return type:

bool or None

property google_api_key: str | None

The Google Spreadsheet API key required for access. Defaults to None.

Note

Be sure to generate your Google Spreadsheet API key at Google’s API Services / Credentials.

Warning

To load data from Google Sheets, the Data.google_spreadsheet_key() must be set, and must have access to the spreadsheet indicated by the spreadsheet key.

Return type:

str or None

property google_spreadsheet_key: str | None

The key or spreadsheetId value for the Google Sheets spreadsheet from which you wish to load data. Defaults to None.

Hint

If you need help finding your spreadsheet key, please review the Google Sheets API Overview

Warning

To load data from Google Sheets, the Data.google_api_key() must be set, and must have access to the spreadsheet indicated by the spreadsheet key.

Return type:

str or None

property google_spreadsheet_range: str | None

The Google Sheets A1 or R1C1 notation cell range from which to retrieve data. Defaults to None.

Note

If set, this property takes precedence over Data.start_column(), Data.end_column(), Data.start_row(), and Data.end_row().

Hint

For more details on how to determine and provide the spreadsheet range, please review the relevant Google Sheets API documentation.

Warning

To load data from Google Sheets, the Data.google_api_key() and Data.google_spreadsheet_key() must both be set.

Return type:

str or None

property item_delimiter: bool | str | None

Item or cell delimiter used when parsing CSV data. If None or False, defaults to the tab character `` `` if a tab character is found in the CSV string. If no tab character is found, defaults to ','.

Return type:

str or bool or None

property line_delimiter: str | None

The string used to delimit records (lines) when parsing CSV data. Defaults to None, which assumes '\n'.

Return type:

str or None

property parse_date: CallbackFunction | None

A JavaScript callback function to parse string representations of dates into JavaScript timestamps. Should return an integer timestamp on success. Defaults to None.

Return type:

CallbackFunction or None

property parsed: CallbackFunction | None

A JavaScript callback function to access the parsed columns (the two-dimentional input data array) directly before they are interpreted into series data and categories. The function should return false to stop completion, or call (in JavaScript) this.complete() to continue asynchronously. Defaults to None.

Return type:

CallbackFunction or None

property rows: List[List[int | str | float | Decimal | None | EnforcedNullType]] | None

The data itself represented in a tabular form. Expects an iterable of iterables, where each second-level iterable represents a row of data. Defaults to None.

my_data = Data()
my_data.rows = [
  [None, 'Apples', 'Pears', 'Oranges'], # categories
  ['Ola', 1, 4, 3], # first series for "Ola"
  ['Kari', 5, 4, 2] # second series for "Kari"
]

Note

Each cell in the second-level iterable can either be a str, numeric value, None, or EnforcedNullType.

Hint

Provided that Data.switch_rows_and_columns() is not set, the rows will be interpreted as series.

Return type:

None or list of list instances with str, numeric, None, or EnforcedNullType members

property rows_url

A URL to a remote JSON dataset, structured as a row array. Defaults to None.

Note

Will be fetched when the chart is created using Ajax.

Return type:

str or None

property series_mapping: dict[str, int] | None

A dictionary used to indicate where point properties are to be found in the data. Property names are the keys, while the values are the column indices indicating where in the CSV the data for that point is to be found. Defaults to None.

Return type:

dict with str keys and int values, or None.

property start_column: int | None

In tabular input data, the first column (indexed by 0) to use. If None, defaults to 0.

Return type:

int or None

property start_row: int | None

In tabular input data, the first row (indexed by 0) to use. If None, defaults to 0.

Return type:

int or None

property switch_rows_and_columns: bool | None

If True, swiches the interpretation of columns and rows so that Data.columns() effectively becomes rows of the data while Data.rows() is interpreted as the series of data. Defaults to False.

Return type:

bool or None

property table: str | None

An HTML table (in str form), or the ID of such a table found in the browser DOM, which should be parsed to extract the data intended for visualization. Defaults to None.

See also

The object has closely-related properties that determine which part of the HTML table should be used when constructing the chart and to configure how the table string should be parsed. In particular, please review:

Return type:

str or None