`.color_axis`

class: `ColorAxis`

class ColorAxis(**kwargs)[source]

A color axis for series.

Visually, the color axis will appear as a gradient or as separate items inside the legend, depending on whether the axis is scalar or based on data classes.

See also

For supported color formats, see the documentation article about colors.

A scalar color axis is represented by a gradient. The colors either range between the ColorAxis.min_color() and the ColorAxis.max_color(), or for more fine-grained control the colors can be defined in ColorAxis.stops(). Often times, the color axis needs to be adjusted to get the right color spread for the data. In addition to stops, consider using a logarithmic axis type, or setting min and max to avoid the colors being determined by outliers.

Note

When ColorAxis.data_classes() are used, the ranges are subdivided into separate classes like categories based on their values. This can be used for ranges between two values, but also for a true category. However, when your data is categorized, it may be as convenient to add each category to a separate series.

Warning

ColorAxis does not work with the following series types:

sankey

sunburst

dependency wheels

network graphs

wordclouds

venn diagrams

solidgauge

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: AxisAccessibility | None

Accessibility options for an axis object.

Return type:: AxisAccessibility or None

property angle: int | float | Decimal | None

In a polar chart, this is the angle of the Y axis in degrees, where 0 is up and 90 is right. Defaults to 0.

Note

The angle determines the position of the axis line and the labels, though the coordinate system is unaffected.

Return type:: numeric or None

property ceiling: int | float | Decimal | None

The highest allowed value for automatically computed axis extremes. Defaults to None.

Return type:: numeric or None

property class_name: str | None

A class name that can then be used for styling the axis using CSS. Defaults to None.

Warning

The the class_name is applied to group elements for the grid, axis elements, and labels.

Return type:: str or None

property crossing: int | float | Decimal | None

The value on a perpendicular axis where this axis should cross. Defaults to None.

Tip

This

is typically used on mathematical plots where the axes cross at 0.

Warning

When .crossing is set, space will not be reserved at the sides of the chart for axis labels and title, so those may be clipped. In this case, it is better to place the axes without the .crossing option.

rtype:

numeric

property data_class_color: str | None

Determines how to set each data class’ color if no individual color is set. The default value, 'tween', computes intermediate colors between ColorAxis.min_color() and ColorAxis.max_color(). The other possible value, 'category', pulls colors from the global or chart specific colors array.

Defaults to 'tween'.

Return type:: str or None

property data_classes: List[DataClass] | None

A collection of data classes or ranges for the choropleth map. If None, the color axis will be scalar and values will be distributed as a gradient between the minimum and maximum colors. Defaults to None.

Return type:: list of DataClass instances, or None

property end_on_tick: bool | None

If True forces the axis to end on a tick. Defaults to False for XAxis, True for YAxis, and False for ZAxis.

Hint

Use this option with the GenericAxis.max_padding() setting to control the axis end.

Warning

This option is always disabled on a YAxis, when panning type is either y or xy.

Return type:: bool or None

property events: AxisEvents | None

Event handlers for the axis.

Return type:: SeriesEvents or None

property floor: int | float | Decimal | None

The lowest allowed value for automatically computed axis extremes. Defaults to None.

Return type:: numeric or None

property grid_line_color: str | Gradient | Pattern | None

Color of the grid lines extending the ticks across the plot area. Defaults to '#e6e6e6'.

Return type:: str, Gradient, Pattern`, or None

property grid_line_dash_style: str | None

Name of the dash style to use for the grid lines. Defaults to Solid.

Accepts one of the following values:

‘Dash’,

‘DashDot’,

‘Dot’,

‘LongDash’,

‘LongDashDot’,

‘LongDashDotDot’,

‘ShortDash’,

‘ShortDashDot’,

‘ShortDashDotDot’,

‘ShortDot’,

‘Solid’

Return type:: str or None

property grid_line_interpolation: str | None

Whether the grid lines should draw as a polygon with straight lines between categories, or as circles. Defaults to None.

Acceptable values are:

'circle'

'polygon'

Warning

Only applies to polar charts.

Return type:: str or None

property grid_line_width: int | float | Decimal | None

The width of the grid lines extending the ticks across the plot area. Defaults to 0 for XAxis, 1 for YAxis, and None for ZAxis.

Return type:: numeric or None

property grid_z_index: int | float | Decimal | None

The Z-index of the grid lines. Defaults to 1.

Return type:: numeric or None

property height: int | float | Decimal | str | None

The height of the color axis, expressed either in pixels or as a percentage of the total plot height. Defaults to None.

Return type:: numeric or str or None

property id: str | None

An id assigned to the axis. Defaults to None.

Hint

This can be used after rendering to get a pointer to the axis object through the (JavaScript) chart.get() method.

Return type:: str or None

property labels: AxisLabelOptions | None

Configuration settings for the axis labels, which show the number or category for each tick. Defaults to None.

Return type:: AxisLabeLOptions or None

property layout: str | None

The layout of the color axis. Defaults to None.

Accepts either:

'horizontal'

'vertical'

If None, the color axis will have the same layout as the legend.

Return type:: str or None

property line_color: str | Gradient | Pattern | None

The color of the line marking the axis itself. Defaults to '#ccd6eb'.

Return type:: str, Gradient, Pattern`, or None

property margin: int | float | Decimal | None

If there are multiple axes on the same side of the chart, the margin between the axes, expressed in pixels. Defaults to 0 for vertical axes, 15 for horizontal axes.

Return type:: numeric or None

property marker: AxisMarker | None

The triangular marker on a scalar color axis that points to the value of the hovered area. To disable the marker, set the value to None. Defaults to None.

Return type:: AxisMarker or None

The maximum value of the axis. If None, the max value is automatically calculated. Defaults to None.

Note

If the GenericAxis.end_on_tick() is True, the max value might be rounded up.

Warning

If a GenericAxis.tick_amount() is set, the axis may be extended beyond the set max in order to reach the given number of ticks. The same may happen in a chart with multiple axes, determined by Chart.align_ticks() where a tick_amount is applied internally.

Return type:: numeric or None

property max_color: str | Gradient | Pattern | None

The color used to represent the maximum value of the color axis. Defaults to '#003399'.

Unless data_classes or stops are set, the gradient ends at this value.

Return type:: str, Gradient, Pattern`, or None

property max_padding: int | float | Decimal | None

Padding of the max value relative to the length of the axis. Defaults to 0.01.

For example, a value of 0.05 will make a 100px axis 5px longer.

Hint

This is useful when you don’t want the highest data value to appear on the edge of the plot area.

Warning

When the GenericAxis.max() option is set or a max extreme is set using (JavaScript) axis.setExtremes(), the max_padding will be ignored.

Return type:: numeric or None

The minimum value of the axis. If None, the min value is automatically calculated. Defaults to None.

Note

If the GenericAxis.start_on_tick() is True, the min value might be rounded down.

Warning

The automatically-calculated min value is also affected by:

GenericAxis.floor()

GenericAxis.soft_min()

GenericAxis.min_padding()

GenericAxis.min_range()

GenericTypeOptions.threshold()

SeriesOptions.soft_threshold()

Return type:: numeric or None

property min_color: str | Gradient | Pattern | None

The color used to represent the minimum value of the color axis. Defaults to '#e6ebf5'.

Unless data_classes or stops are set, the gradient starts at this value.

Return type:: str, Gradient, Pattern`, or None

property min_padding: int | float | Decimal | None

Padding of the min value relative to the length of the axis. Defaults to 0.01.

For example, a value of 0.05 will make a 100px axis 5px longer.

Hint

This is useful when you don’t want the lowest data value to appear on the edge of the plot area.

Warning

When the GenericAxis.min() option is set or a min extreme is set using (JavaScript) axis.setExtremes(), the min_padding will be ignored.

Return type:: numeric or None

property minor_grid_line_color: str | Gradient | Pattern | None

Color of the minor (secondary) grid lines. Defaults to '#f2f2f2'.

Return type:: str, Gradient, Pattern`, or None

property minor_grid_line_dash_style: str | None

Name of the dash style to use for the grid lines. Defaults to Solid.

Accepts one of the following values:

‘Dash’,

‘DashDot’,

‘Dot’,

‘LongDash’,

‘LongDashDot’,

‘LongDashDotDot’,

‘ShortDash’,

‘ShortDashDot’,

‘ShortDashDotDot’,

‘ShortDot’,

‘Solid’

Return type:: str or None

property minor_grid_line_width: int | float | Decimal | None

Width of the minor, secondary grid lines. Defaults to 1.

Return type:: numeric or None

property minor_tick_color: str | Gradient | Pattern | None

Color for the minor tick marks. Defaults to '#999999'.

Return type:: str, Gradient, Pattern`, or None

property minor_tick_interval: int | float | Decimal | str | None

Specific tick interval in axis units for the minor ticks. Defaults to None.

On a linear axis, if "auto", the minor tick interval is calculated as a fifth of the GenericAxis.tick_interval(). If None, minor ticks are not shown.

On logarithmic axes, the unit is the power of the value. For example, setting the minor_tick_interval to 1 puts one tick on each of 0.1, 1, 10, 100, etc. Setting the value to 0.1 produces 9 ticks between 1 and 10, 10 and 100 etc.

Return type:: numeric or str or None

property minor_tick_length: int | float | Decimal | None

The length of the minor tick marks, in pixels. Defaults to 2.

Return type:: numeric or None

property minor_tick_position: str | None

The position of the minor tick marks relative to the axis line. Defaults to 'outside'.

Accepts either:

'outside'

'inside'

Return type:: str or None

property minor_tick_width: int | float | Decimal | None

The width of the minor tick marks, in pixels. Defaults to 0.

Return type:: numeric or None

property minor_ticks: bool | None

Enable (True) or disable (False) minor ticks. Defaults to False.

Note

Unless GenericAxis.minor_tick_interval() is set, the minor tick interval is calculated as a fifth of the tickInterval.

Note

On a logarithmic axis, minor ticks are laid out based on a best guess, attempting to fit approximately 5 minor ticks between each major tick.

Warning

On category axes (where text is displayed in each position, rather than a numerical value), minor ticks are not supported.

Return type:: bool or None

property panning_enabled: bool | None

If True, allows the axis to pan. False prevents the axis from panning. Defaults to True.

Note

If Chart.panning() is True and this option is False, then this specific axis will not pan.

Return type:: bool or None

property reversed: bool | None

If True, reverses the axis so that the highest number is closest to the origin. Defaults to None.

Note

If the chart is inverted, the XAxis is reversed by default.

Return type:: bool or None

property show_first_label: bool | None

If True, renders the first tick label by the axis. Defaults to True.

Return type:: bool or None

property show_in_legend: bool | None

Whether to display the color axis in the legend. Defaults to True.

Return type:: bool

property show_last_label: bool | None

If True, renders the last tick label by the axis. If None, defaults to True on cartesian charts and False on polar charts.

Return type:: bool or None

property soft_max: int | float | Decimal | None

A soft maximum for the axis. Defaults to None.

If the series data maximum is less than this, the axis will stay at this maximum, but if the series data maximum is higher than this value, the axis will flex to show all data.

Return type:: numeric or None

property soft_min: int | float | Decimal | None

A soft minimum for the axis. Defaults to None.

If the series data minimum is less than this, the axis will stay at this minimum, but if the series data minimum is higher than this value, the axis will flex to show all data.

Return type:: numeric or None

property start_of_week: int | None

For datetime axes, this decides where to put the tick between weeks. Defaults to 1 (Monday).

Note

0 = Sunday, 1 = Monday, etc.

Hint

As a convenience, if you supply a string with the day of week (e.g. 'Monday'), the Highcharts for Python library wlil automatically convert it to the appropriate numerical value.

Return type:: int or None

property start_on_tick: bool | None

If True forces the axis to start on a tick. Defaults to False for XAxis, True for YAxis, and False for ZAxis.

Hint

Use this option with the GenericAxis.min_padding() setting to control the axis start.

Warning

This option is always disabled on a YAxis, when panning type is either y or xy.

Return type:: bool or None

property stops: List[List[str | int | float | Decimal]] | None

Color stops for the gradient in a color axis. Defaults to None.

Hint

Use this in cases where a linear gradient between a min_color and max_color is not sufficient.

Note

Expects an iterable of 2-member iterables. Each 2-member iterable should be composed of a number and a string. The number should be a value between 0 and 1 which assigns the relative position of the color in the gradient, while the string should represent the color itself.

Return type:: list of list, where each second list consists of a float and a str / or None

property tick_amount: int | None

The amount of ticks to draw on the axis. Defaults to None.

Hint

This provides greater control for aligning the ticks of multiple charts or panes within a chart.

Warning

This option overrides the GenericAxis.tick_pixel_interval() option.

Note

This option only has an effect on linear axes. Datetime, logarithmic, or category axes are not affected.

Return type:: int or None

property tick_color: str | Gradient | Pattern | None

Color for the main tick marks. Defaults to '#ccd6eb'.

Return type:: str, Gradient, Pattern`, or None

property tick_interval: int | float | Decimal | None

The interval of the tick marks in axis units. Defaults to None.

When None, the tick_interval is automatically computed to approximately follow GenericAxis.tick_pixel_interval() on linear and datetime axes. On category axes, None will default to 1 (one category).

Note

Datetime axes are based on milliseconds, so for example an interval of one day is expressed as 24 * 3600 * 1000.

On logarithmic axes, the unit is the power of the value. For example, setting the tick_interval to 1 puts one tick on each of 0.1, 1, 10, 100, etc. Setting the value to 0.1 produces 9 ticks between 1 and 10, 10 and 100 etc.

Warning

If the chart has multiple axes, the GenericAxis.align_ticks() setting may interfere with tick_interval.

Return type:: numeric or str or None

property tick_length: int | float | Decimal | None

The length of the main tick marks, in pixels. Defaults to 10.

Return type:: numeric or None

property tick_pixel_interval: int | float | Decimal | None

If tick_interval is None, this setting establishes the approximate interval between major tick marks, expressed in pixels. Defaults to 100.

Warning

Does not apply to categorized axes.

Note

The tick interval is also influenced by the min_tick_interval setting, which, by default, prevents ticks from being denser than the data points.

Return type:: numeric or None

property tick_position: str | None

The position of the major tick marks relative to the axis line. Defaults to 'outside'.

Accepts either:

'outside'

'inside'

Return type:: str or None

property tick_positioner: CallbackFunction | None

A JavaScript callback function returning an array defining where the ticks are laid out on the axis.

Warning

This overrides the default behaviour of tick_pixel_interval and tick_interval.

The automatic tick positions are accessible (in JavaScript) through this.tickPositions and can be modified by the callback.

Return type:: CallbackFunction or None

property tick_positions: List[int | float | Decimal] | None

An array that explicitly positions the major tick marks along the axis. Defaults to None.

Warning

Setting tick positions explicitly using this setting overrides the default behavior of tick_pixel_interval and tick_interval.

Return type:: list of numeric values, or None

property tick_width: int | float | Decimal | None

The width of the main tick marks, in pixels. Defaults to 0 on category axes, otherwise defaults to 1.

Return type:: numeric or None

property tickmark_placement: str | None

If 'on', the tick mark is placed in the center of the category. If 'between', the tick mark is placed between categories. If None, defaults to 'between' if tick_interval is 1, otherwise defaults to 'on'.

Warning

Applies to category axes only.

Return type:: str or None

property type: str | None

The type of axis. Defaults to 'linear'.

Accepts the following values:

'linear'

'logarithmic'

'datetime'

'category'

Note

In a 'datetime' axis, the numbers are given in milliseconds, and tick marks are placed on appropriate values like full hours or days.

Note

In a 'category' axis, either the categories setting determines the categories rendered on the axis, or the categories are derived from the point names of the chart’s series.

Return type:: str or None

property unique_names: bool | None

If True, points are placed on the axis according to their names. If the same point name is repeated in the same or another series, the point is placed on the same axis position as other points of the same name. When False, the points are laid out in increasing positions regardless of their names, and the axis category will take the name of the last point in each position. Defaults to True.

Warning

Applies only to category axes.

Return type:: bool or 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.

Warning

Only applies to datetime axes.

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

property visible: bool | None

If True, renders the axis (including title, line, ticks, and labels). If False, hides the axis (including title, line, ticks, and labels). Defaults to True.

Return type:: bool or None

property width: int | float | Decimal | str | None

The width of the color axis, expressed either in pixels or as a percentage of the total plot width. Defaults to None.

Return type:: numeric or str or None

property z_index: int | float | Decimal | None

The Z-index for the axis group (including title, line, ticks, and labels). Defaults to '2'.

Return type:: numeric or None

.color_axis

class: ColorAxis

`.color_axis`

class: `ColorAxis`