Utilities

Helper functions and classes that are not plot windows or drawable objects.

Number formatting

kaxe.koundTeX(num: float) → str

Format a number for axis labels using LaTeX-style notation.

Small integers are returned as plain numbers. Very small or very large values use scientific notation. Thousands separators use \smallSpace.

Parameters:: num (float) – Numeric value to format.
Returns:: LaTeX math string, e.g. "$5*10^{-4}$" or "$314$".
Return type:: str

Examples

>>> koundTeX(0.005)
'$5.0*10^{-3}$'
>>> koundTeX(314)
'$314$'

Global settings

kaxe.setSetting(**kwargs)

Set global Kaxe runtime settings.

Parameters:

**kwargs –

Supported keys:

removeInfobool: When True, suppress progress bars and bake timing logs. Useful in notebooks and batch scripts.
jupyterLoadingThresholdfloat: Seconds before a progress bar appears in Jupyter (default 1.0). Fast plots stay quiet.
jupyterDisplayWidthint: Width in pixels for inline notebook display (default 800).

Examples

>>> setSetting(removeInfo=True)

Note

Currently supported keys: removeInfo (bool) — suppress progress bars and bake timing logs.

Colors

kaxe.to_rgba(color) → tuple[int, int, int, int]

Normalize a color to an RGBA tuple with channels in 0–255.

Parameters:

color (str, sequence, or numpy array) – Hex string (e.g. "#FF5154"), named color (e.g. "red"), or RGB/RGBA sequence.

Returns:

(r, g, b, a) with integer channels 0–255.

Return type:

tuple[int, int, int, int]

Raises:

TypeError – If color is a Colormap instance.
ValueError – If the color format is not recognized.

kaxe.setDefaultColors(colorList: list)

Replace the global default series palette.

Parameters:: colorList (list) – Colors for the series cycle. Entries may be RGBA tuples or hex/named color strings (see kaxe.to_rgba()).

kaxe.resetColor() → None: Reset the global series color cycle to before the first palette color.

kaxe.getRandomColor() → tuple

Return the next color from Kaxe’s default series palette.

Colors rotate through the built-in Okabe–Ito palette. Each plot window maintains its own cycle for objects added without an explicit color; this global function is for manual use (e.g. color=kaxe.getRandomColor()). Call resetColor() to restart the global cycle manually.

Returns:: RGBA color tuple, e.g. (230, 159, 0, 255).
Return type:: tuple

Colormaps

class kaxe.Colormap(colorGradientSteps: list | tuple)

A class to represent a colormap that interpolates colors from a gradient.

Parameters:: colorGradientSteps (Union[list, tuple]) – A list or tuple of colors representing the gradient steps. Colors can be in hexadecimal string format or RGBA arrays.

getColor(value: int | float, start: int | float, end: int | float)

Get the interpolated color from the color gradient steps based on the input value.

Parameters:

value (Union[int, float]) – The value for which the color needs to be determined.
start (Union[int, float]) – The start value of the range.
end (Union[int, float]) – The end value of the range.

Returns:

The interpolated color from the color gradient steps.

Return type:

color

Notes

If value is less than start, the first color in the gradient steps is returned.
If value is greater than end, the last color in the gradient steps is returned.
The interpolation is linear between the two nearest colors in the gradient steps.

Examples

>>> cmap.getColor(3.5, 0, 10)
    (125, 215, 51, 255)

map_array(values: ndarray, start: int | float, end: int | float) → ndarray

Map a numeric array to RGBA colors using this colormap.

Returns an array with shape (*values.shape, 4) and dtype uint8.

setAlpha(alpha255)

Update the alpha (transparency) value for each color in the color gradient steps.

Parameters:: alpha255 (int) – The alpha value to set, ranging from 0 to 255, where 0 is fully transparent and 255 is fully opaque.
Return type:: Colormap

class kaxe.Colormaps

A collection of predefined colormaps for various color schemes.

standard

Default sequential colormap (blue to green, colorblind-safe).

Type:: Colormap

green

A colormap with various shades of green.

Type:: Colormap

brown

A colormap with various shades of brown.

Type:: Colormap

blue

A colormap with various shades of blue.

Type:: Colormap

yellow

A colormap with various shades of yellow.

Type:: Colormap

cream

A colormap with a cream color scheme.

Type:: Colormap

red

A single color colormap with the color red.

Type:: SingleColormap

class kaxe.SingleColormap(color, spread=0.3, total=10)

SingleColormap is a subclass of Colormap that generates a colormap based on a single color.

Parameters:

color (str or list or tuple) – The base color for the colormap. If a string is provided, it should be a hex color code. If a list or tuple is provided, it should contain RGB or RGBA values.
spread (float, optional) – A float larger than 1 describing the spread of the colors Default is [0.3, 0.7].
total (int, optional) – The total colors in the colormap

Symbols

kaxe.Symbol: alias of symbol

class kaxe.symbol

Themes

class kaxe.Themes

A class used to represent different themes for plotting.

A4Large

A dictionary containing settings for a large A4 plot.

Type:: dict

A4Medium

A dictionary containing settings for a medium A4 plot.

Type:: dict

A4Small

A dictionary containing settings for a small A4 plot.

Type:: dict

A4Slim

A dictionary containing settings for a slim A4 plot.

Type:: dict

A4Mini

A dictionary containing settings for a mini A4 plot.

Type:: dict

Axis

The axis object used by most plots exposes additional attributes and methods:

class kaxe.Axis(directionVector: tuple, titleNormal: tuple, numberOnAxisGoalReference: str)

Axis is a class for creating and managing axes in a plot.

add(text: str, pos: int | float, showLine: bool = True)

Add markers to the axis.

Parameters:

text (str) – The text label for the marker.
pos (int | float) – The position of the marker on the axis.
showLine (bool, optional) – Whether to show a line for the marker (default is True).

Ghost legends

Add legend entries that are not tied to a specific plotted object:

class kaxe.GhostLegend(text: str, color: tuple, symbol: str)

Adds a legend

Parameters:

text (str) – The text to be displayed in the legend.
symbol (symbols) – The symbol to be used in the legend.
color (tuple) – The color to be used for the legend text. If not provided, the default color will be used.

Excel data loader

Load a rectangular range from an .xlsx workbook. Column indices are 1-based (Excel convention):

import kaxe

# Sheet "Results", columns A–B, rows 2 through last row
table = kaxe.data.loadExcel("results.xlsx", "Results", top=(1, 2), bottom=(2, -1))

x = [row[0] for row in table]
y = [row[1] for row in table]
plt = kaxe.Plot()
plt.add(kaxe.Points2D(x, y))

Set flip=True to transpose rows and columns. See Recipes for a full example.

data.loadExcel(sheet: str, top: tuple, bottom: tuple, flip: bool = False)

Load data from an Excel sheet within a specified range.

Parameters:

fname (str) – The filename of the Excel workbook.
sheet (str) – The name of the sheet to load data from.
top (tuple) – A tuple (column, row) representing the top-left corner of the range.
bottom (tuple) – A tuple (column, row) representing the bottom-right corner of the range. If the row is -1, it will be set to the maximum row of the sheet.
flip (bool, optional) – If True, the data will be transposed (flipped). Defaults to False.

Returns:

A 2D list containing the data from the specified range in the Excel sheet.

Return type:

list

Point thinning

Reduce large point series before adding them to a plot — especially useful for SVG export where millions of markers make files slow to load:

import kaxe

# Cap at 5000 points (uniform index sampling)
x_thin, y_thin = kaxe.thin_points(x, y, max_points=5000)

# Keep every 10th point
x_thin, y_thin = kaxe.thin_points(x, y, every=10)

# Min spacing in data coordinates
x_thin, y_thin = kaxe.thin_points(x, y, min_distance=0.05)

# Min spacing in screen pixels (needs plot with fixed bounds)
plt = kaxe.Plot([0, 10, 0, 10])
plt.theme(kaxe.Themes.A4Medium)
x_thin, y_thin = kaxe.thin_points(x, y, min_distance=3, space="pixel", plot=plt)

plt.add(kaxe.Points2D(x_thin, y_thin))

Provide exactly one of every, min_distance, or max_points. Optional z is thinned with the same indices: x, y, z = kaxe.thin_points(x, y, z, every=5).

kaxe.thin_points(x, y, z=None, *, every: int | None = None, min_distance: float | None = None, max_points: int | None = None, space: str = 'data', plot=None) → tuple

Reduce a large point series before plotting.

Provide exactly one of every, min_distance, or max_points.

Parameters:

x (array-like) – Point coordinates in input order.
y (array-like) – Point coordinates in input order.
z (array-like, optional) – Optional third coordinate; thinned with the same indices as x and y.
every (int, optional) – Keep every nth point by index (always keeps first and last).
min_distance (float, optional) – Keep points at least this far apart. Uses data coordinates by default; with space="pixel", distance is measured in screen pixels.
max_points (int, optional) – Cap the number of points via uniform index sampling (always keeps first and last when possible).
space (str, optional) – "data" (default) or "pixel". Only affects min_distance.
plot (plot window, optional) – Required when space="pixel" and min_distance is set. Must have fixed axis bounds and width/height (e.g. kaxe.Plot([x0, x1, y0, y1]) with theme() applied).

Returns:

(x, y) or (x, y, z) with the thinned coordinates.

Return type:

tuple