.z_axis

---

class: ZAxis

class ZAxis(**kwargs)

Configuration settings for the Z axis or depth axis in 3D charts.

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 align_ticks: bool | None

If True and using multiple axes, the ticks of two or more opposite axes will automatically be aligned by adding ticks to the axis or axes with the least ticks, as if tick_amount were specified. This can be prevented by setting align_ticks to False.

Defaults to True.

Hint

If the grid lines look messy, it’s a good idea to hide them for the secondary axis by setting grid_line_width to 0.

Warning

If start_on_tick or end_on_tick in the axis options are set to False, then tick alignment will be disabled for the axis.

Warning

Aways disabled for logarithmic axes.

Returns:

Flag indicating whether ot align ticks along the axes.

Return type:

bool or None

property allow_decimals: bool | None

If True, allow decimals in the axis’ ticks. If None, decimals are allowed on small scale axes. Defaults to None.

Hint

When counting integers, like persons or hits on a web page, decimals should be avoided in the labels.

Return type:

bool or None

property alternate_grid_color: str | Gradient | Pattern | None

When using an alternate grid color, a band is painted across the plot area between every other grid line. This setting determines the color of that band. Defaults to None.

Return type:

str, Gradient, Pattern`, 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 breaks: List[AxisBreak] | None

A collection that defines breaks to render in the axis. Defaults to None.

Note

The sections defined as breaks will be left out and all the points shifted closer to each other.

Return type:

list of AxisBreak, or None

property categories: List[str] | None

If categories are present for the x-axis, displays category names along the x-axis instead of numerical values. Defaults to None.

Hint

While categories can also be defined by giving each data point a name and setting axis type to 'category', if you have multiple series, best practice remains using the categories setting for ease of maintenance.

Return type:

list of str, 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 date_time_label_formats: DateTimeLabelFormats | None

For a datetime axis, the scale will automatically adjust to the appropriate unit. This setting gives the default string representations used for each unit. Defaults to None.

Note

For intermediate values, different units may be used, for example the day unit can be used on midnight and hour unit used for intermediate values on the same axis.

See also

• DateTimeLabelFormats

Return type:

DateTimeLabelFormats 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 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 linked_to: int | None

The index of another axis that this axis is linked to.

When an axis is linked to a master axis, it will take the same extremes as the master as assigned by NumericAxis.min() or NumericAxis.max() or by the (JavaScript) setExtremes() method. It can be used to show additional info, or to ease reading the chart by duplicating the scales.

Return type:

str 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 max: int | float | Decimal | date | datetime | 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_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

property min: int | float | Decimal | date | datetime | 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_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 min_range: int | float | Decimal | None

The minimum range to display on this axis. The entire axis will not be allowed to span over a smaller interval than this, particularly when zooming. Defaults to None.

For example, for a datetime axis the main unit is milliseconds. If min_range is set to 3600000, the user won’t be able to zoom in more than to one hour.

If None, the min_range for the x-axis will automatically be set to five times the smallest interval between any of the data points.

On a logarithmic axis, the unit for the minimum range is the power. So a min_range of 1 means that the axis can be zoomed to 10-100, 100-1000, 1000-10,000 etc.

Warning

The following settings also impact how the extremes of the axis are computed:

• NumericAxis.min_padding()

• NumericAxis.max_padding()

• NumericAxis.start_on_tick()

• NumericAxis.end_on_tick()

Return type:

numeric or None

property min_tick_interval: int | float | Decimal | None

The minimum tick interval allowed in axis values. Defaults to None, which applies the closest distance between two points on the axis.

For example, this setting can be used to prevent the axis from showing hours as minor tick marks.

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 offset: int | float | Decimal | None

The distance in pixels from the plot area to the axis line. Defaults to None.

A positive offset moves the axis (along with its line, labels, and ticks) away from the plot area. This is typically used when two or more axes are displayed on the same side of the plot.

With multiple axes, the offset is dynamically adjusted to avoid collision, though this can be overridden by setting offset explicitly.

Return type:

numeric or None

property opposite: bool | None

If True, displays the axis on the opposite side of where it would normally appear. Defaults to False.

Vertical axes would normally appear on the left side of the chart, while horizontal axes would normally appear on the bottom of the chart. Thus, the opposite side would be the right and top respectively.

Hint

This feature is typically used with dual or multiple axes.

Return type:

bool or None

property pane: int | None

Indicates the index in the panes array. When None, the first pane will be used. Defaults to None.

Warning

Used for circular gauges and polar charts.

Return type:

int 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 plot_bands: List[PlotBand] | None

A collection of colored bands stretching across the plot area which can be used to visually mark an interval along the axis. Defaults to None.

Note

In a gauge chart, a plot band on the YAxis (value axis) will stretch along the perimeter of the gauge.

Return type:

list of PlotBand instances, or None

property plot_lines: List[PlotLine] | None

A collection of lines stretching across the plot area which can be used to visually mark specific values on the axis. Defaults to None.

Return type:

list of PlotLine instances, 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 reversed_stacks: bool | None

This option determines how stacks should be ordered within a group. Setting this to True will reverse the order of series within a group relative to its automatic ordering.

For example, if XAxis.reversed` is True, then the default behavior is to reverse the order of the series so that the first series comes last in a group. To retain the original order, set this option to True.

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_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 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 title: AxisTitle | None

The axis title, displayed next to the axis line. Defaults to None.

Return type:

AxisTitle 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

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.

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

property zoom_enabled: bool | None

If True, the axis supports zooming in to view more granular sub-sections of the data. If False, the axis will not zoom. Defaults to True.

Hint

If Chart.zoom_type() is set, setting this value to False can override the ability to zoom in on this specific axis.

Return type:

bool or None