.data_grouping

class: DataGroupingOptions

class DataGroupingOptions(**kwargs)[source]

Data grouping configures sampling the data values into larger blocks in order to ease readability and increase performance of the JavaScript charts.

Highcharts Stock by default applies data grouping when the points become closer than the number of pixels specified by the .group_pixel_width setting.

Note

If data grouping is applied, the grouping information of grouped points can be read (in JavaScript) from Point.dataGroup.

Caution

In Highcharts for Python and Highcharts JS, usage of the data grouping requires the modules/datagrouping.js JavaScript module. In Highcharts Stock for Python, it is included by default.

Caution

If point options other than the data itself are set, for example name, color, or custom properties, the grouping logic will not know how to group it. In this case, the options of the first point instance are copied over to the group point. This can be altered through a custom approximation function.

Class Inheritance
Inheritance diagram of DataGroupingOptions

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

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 anchor: str | None

Specifies how the points should be located on the X axis inside the group. Defaults to 'start'.

Available options:

  • 'start' places the point at the beginning of the group (e.g. range 00:00:00 - 23:59:59 -> 00:00:00)

  • 'middle' places the point in the middle of the group (e.g. range 00:00:00 - 23:59:59 -> 12:00:00)

  • 'end' places the point at the end of the group (e.g. range 00:00:00 - 23:59:59 -> 23:59:59)

Return type:

str or None

property approximation: str | CallbackFunction | None

The method of approximation within a group. For example, when 30 days are grouped into a one month period, this property determines what value should represent the entire group.

Accepts the following values if not using a custom function:

  • 'average'

  • 'averages'

  • 'hlc'

  • 'ohlc'

  • 'open'

  • 'high'

  • 'low'

  • 'close'

  • 'sum'

  • 'range'

  • 'windbarb'

The default value will depend on the series type for which data grouping is being applied:

  • WindBarbSeries will default to 'windbarb',

  • OHLCSeries, Candlestick, will default to 'ohlc' which are then calculated from the open, high, low, and close values.

  • HLCSeries will default to 'hlc', which then calculate the grouped values from the high, low, and close values.

  • For range-type series, will default to 'range', which then calculates grouped values from the low and high-end values.

  • For line-type series, will default to 'average'.

  • For column-type series will default to 'sum'.

  • For all other data, will default to 'averages'.

Custom aggregate methods can be added by assigning a callback function as the approximation. This function should take a numeric array as the argument and should return a single numeric value or (JavaScript) null.

Note

The numeric array will never contain null values, only true numbers. Instead, if null values are present in the raw data, the numeric array will have a (JavaScript) .hasNulls property set to true.

For single-value data sets the data is available in the first argument of the callback function. For OHLC data sets, all the open values are in the first argument, all high values in the second, etc.

Tip

Grouping meta data is available in the (JavaScript) approximation callback via this.dataGroupInfo. It can be used to extract information from the raw data.

Return type:

str or CallbackFunction or None

property date_time_label_formats: DateTimeLabelFormats | None

Datetime formats for the header of the tooltip in a stock chart. Defaults to None.

See also

  • DateTimeLabelFormats

Return type:

DateTimeLabelFormats or None

property enabled: bool | None

If True, enables data grouping. Defaults to True.

Return type:

bool or None

property first_anchor: str | None

Specifies how the first grouped point is positioned on the xAxis. Defaults to 'start'.

If first_anchor and/or last_anchor are provided, then those options take precedence over anchor for the first and/or last grouped points.

Supported values are:

  • 'start' places the point at the beginning of the group (e.g. range 00:00:00 - 23:59:59 -> 00:00:00)

  • 'middle' places the point in the middle of the group (e.g. range 00:00:00 - 23:59:59 -> 12:00:00)

  • 'end' places the point at the end of the group (e.g. range 00:00:00 - 23:59:59 -> 23:59:59)

  • 'firstPoint' places the point at the first point in the group (e.g. points at 00:13, 00:35, 00:59 -> 00:13)

  • 'lastPoint' places the point at the last point in the group (e.g. points at 00:13, 00:35, 00:59 -> 00:59)

Return type:

str or None

property forced: bool | None

If True, data grouping is applied no matter how small the intervals are. Defaults to False.

Hint

This can be handy for example when the sum should be calculated for values appearing at random times within each hour.

Return type:

bool or None

property group_all: bool | None

If True, will force data grouping to calculate all grouped points for a given dataset even if not visible. If False, data grouping is calculated only for visible points. Defaults to False.

Note

Setting this option to True prevents for example a column series from calculating a grouped point only for part of the dataset. The effect is similar to SeriesOptions.get_extremes_from_all() but does not affect yAxis extremes.

Return type:

bool or None

property group_pixel_width: int | float | Decimal | None

The approximate data group width, expressed in pixels. Defaults to 30.

Return type:

numeric or None

property last_anchor: str | None

Specifies how the last grouped point is positioned on the xAxis. Defaults to 'start'.

If first_anchor and/or last_anchor are provided, then those options take precedence over anchor for the first and/or last grouped points.

Supported values are:

  • 'start' places the point at the beginning of the group (e.g. range 00:00:00 - 23:59:59 -> 00:00:00)

  • 'middle' places the point in the middle of the group (e.g. range 00:00:00 - 23:59:59 -> 12:00:00)

  • 'end' places the point at the end of the group (e.g. range 00:00:00 - 23:59:59 -> 23:59:59)

  • 'firstPoint' places the point at the first point in the group (e.g. points at 00:13, 00:35, 00:59 -> 00:13)

  • 'lastPoint' places the point at the last point in the group (e.g. points at 00:13, 00:35, 00:59 -> 00:59)

Return type:

str or None

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

An array determining what time intervals the data is allowed to be grouped to. Each array item is an array where the first value is the time unit expressed as a str and the second value is another array of allowed multiples.

Defaults to None, which behaves as:

{
    'units': [
        [
            'millisecond', # unit name
            [1, 2, 5, 10, 20, 25, 50, 100, 200, 500] # allowed multiples
        ],
        [
            'second',
            [1, 2, 5, 10, 15, 30]
        ],
        [
            'minute',
            [1, 2, 5, 10, 15, 30]
        ],
        [
            'hour',
            [1, 2, 3, 4, 6, 8, 12]
        ],
        [
            'day',
            [1]
        ],
        [
            'week',
            [1]
        ],
        [
            'month',
            [1, 3, 6]
        ],
        [
            'year',
            None
        ]
    ]
}
Return type:

list of list of str and list of numerics, or None