.navigator

---

class: Navigator

class Navigator(**kwargs)

The navigator is a small series below the main series, displaying a view of the entire data set. It provides tools to zoom in and out on parts of the data as well as panning across the dataset.

Class Inheritance

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 accessibility: NavigatorAccessibilityOptions | None

Options for configuring accessibility for the navigator.

Return type:

NavigatorAccessibilityOptions or None

property adapt_to_updated_data: bool | None

If True, the navigator and scroll will adapt to updated data in the base X-axis. Defaults to None, which behaves as False.

Hint

When loading data asynchronously, this should be False. Otherwise new data will trigger the navigator to redraw, which will cause unwanted looping.

Return type:

bool or None

property enabled: bool | None

If True, enables the navigator. if False, disables it. Defaults to None, which behaves as True.

Return type:

bool or None

property handles: HandleOptions | None

Options for the handles that allow dragging the zoomed-in area. Defaults to None.

Return type:

HandleOptions or None

property height: int | float | Decimal | None

The height given to the navigator, expressed in pixels. Defaults to 40.

Return type:

numeric or None

property margin: int | float | Decimal | None

The distance from the nearest element (either the X-axis or the X-axis labels), expressed in pixels. Defaults to 25.

Return type:

numeric or None

property mask_fill: str | Gradient | Pattern | None

The color of the mask covering the areas of the navigator series that are currently not visible in the main series. Defaults to 'rgba(102,103,194,0.3)', which is bluish and slightly transparent to see the series below.

Return type:

str, Gradient, Pattern`, or None

property mask_inside: bool | None

If True, renders the mask inside the range marking the zoomed-in data. If False, renders the mask outside the zoomed-in data range. Defaults to None, which behaves as True.

Return type:

bool or None

property opposite: bool | None

If True, renders the navigator on the opposite side when the chart is inverted. Defaults to None, which behaves as False.

Return type:

bool or None

property outline_color: str | Gradient | Pattern | None

The color of the line marking the currently zoomed area in the navigator. Defaults to '#cccccc'.

Return type:

str, Gradient, Pattern`, or None

property outline_width: int | float | Decimal | None

The width of the line marking the currently zoomed-in area of the navigator. Defaults to 1.

Return type:

numeric or None

property series

Options for the navigator series (the series of data drawn in the navigator). Defaults to None, which is equivalent to:

series = AreaSplineSeries(
    fill_opacity = 0.05,
    data_grouping = DataGrouping(smoothed = True),
    line_width = 1,
    marker = Marker(enabled = False)
)

Hint

If the series setting does not have data explicitly provided, it will default to the data of the first series in the chart.

Return type:

SeriesBase or None

property x_axis: XAxis | None

Configuration of the navigator’s X-axis. Defaults to None, which implicitly applies the following:

x_axis = XAxis(
    tick_width = 0,
    line_width = 0,
    grid_line_width = 1,
    tick_pixel_interval = 200,
    labels = AxisLabelOptions(align = left,
                              style = { 'color': '#888' },
                              x = 3,
                              y = -4)
)

Return type:

XAxis or None

property y_axis: YAxis | None

Configuration of the navigator’s X-axis. Defaults to None, which implicitly applies the following:

y_axis = YAxis(
    grid_line_width = 0,
    start_on_tick = False,
    end_on_tick = False,
    min_padding = 0.1,
    max_padding = 0.1
    labels = AxisLabelOptions(enabled = False),
    title = AxisTitle(text = None),
    tick_width = 0
)

Return type:

YAxis or None

---

class: HandleOptions

class HandleOptions(**kwargs)

Options for the handles that allow dragging the zoomed-in area.

Class Inheritance

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 background_color: str | Gradient | Pattern | None

The background color or gradient for the pane. Defaults to '#f2f2f2'.

Returns:

The backgorund color for the handle.

Return type:

str, Gradient, Pattern`, or None

property border_color: str | Gradient | Pattern | None

The color of the pane border. Defaults to '#999999'.

Returns:

The color of the handle border and the stripes inside.

Return type:

str, Gradient, Pattern`, or None

property enabled: bool | None

If True, enables the handles. if False, disables them. Defaults to None, which behaves as True.

Return type:

bool or None

property height: int | float | Decimal | None

The height given to the handles, expressed in pixels. Defaults to 15.

Return type:

numeric or None

property line_width: int | float | Decimal | None

The width of the handle border and the stripes inside, expressed in pixels. Defaults to 1.

Return type:

numeric or None

property symbols: List[str] | None

Configuration of the shapes given to the handles. Defaults to None, which applies ['navigator-handle', 'navigator-handle'].

Note

The symbols setting takes a 2-member collection of str values. These values can either indicate CSS styles (as in the default behavior), a url(...) to a graphic image, or the name of a (JavaScript) SVGRenderer.prototype.symbols callback method.

Return type:

list of str or None

property width: int | float | Decimal | None

The width given to the handles, expressed in pixels. Defaults to 7.

Return type:

numeric or None