Documentation

Theme

class aquarel.theme.Theme(name=None, description=None)[source]

Bases: object

Parameters

name (Optional[str]) –
description (Optional[str]) –

apply()[source]: Applies the theme

apply_transforms()[source]: Applies the themes’ transforms

classmethod from_dict(data)[source]

Initialize a theme from a dictionary

Parameters: data (dict) – theme dictionary to initialize from
Returns: cls

classmethod from_file(filename)[source]

Initialize a theme from a theme file

Parameters: filename (str) – file to load theme dictionary from
Returns: cls

save(path)[source]

Write the template to a JSON template file

Parameters: path (str) – file to write the template to

set_axes(width=None, top=None, bottom=None, left=None, right=None, xmargin=None, ymargin=None, zmargin=None)[source]

Set axis styling options

Parameters

width (Optional[Union[float, int]]) – axis line width, default: 1.0
top (Optional[bool]) – display top axis, default: True
bottom (Optional[bool]) – display bottom axis, default: True
left (Optional[bool]) – display left axis, default: True
right (Optional[bool]) – display right axis, default: True
xmargin (Optional[float]) – padding added to the x-axis, expressed as margin times the data interval, default: 0.05
ymargin (Optional[float]) – padding added to the y-axis, expressed as margin times the data interval, default: 0.05
zmargin (Optional[float]) – padding added to the z-axis, expressed as margin times the data interval, default: 0.05

Returns

self

set_axis_labels(pad=None, size=None, weight=None)[source]

Set axis label styling options.

Parameters

pad (Optional[Union[float, int]]) – padding of the axis label
size (Optional[str]) – font size of the axis label, can be {“xx-small”, “x-small”, “small”, “medium”, “large”, “x-large”, “xx-large”}, default: “medium”
weight (Optional[str]) – font weight of the axis label, can be {“ultralight”, “light”, “normal”, “regular”, “book”, “medium”, “roman”, “semibold”, “demibold”, “demi”, “bold”, “heavy”, “extra bold”, “black”}, default: “normal”

Returns

self

set_color(palette=None, figure_background_color=None, plot_background_color=None, text_color=None, axes_color=None, axes_label_color=None, line_color=None, grid_color=None, tick_color=None, tick_label_color=None, legend_background_color=None, legend_border_color=None)[source]

Sets color options.

Parameters

palette (Optional[List[str]]) – The color palette to cycle through for plot elements, should be list of valid color arguments
figure_background_color (Optional[str]) – the background color of the whole figure
plot_background_color (Optional[str]) – the background color of the plot only
text_color (Optional[str]) – color of text elements (plot title, axis title)
axes_color (Optional[str]) – the color of the axis lines
axes_label_color (Optional[str]) – the color of the axis labels
line_color (Optional[str]) – the line color
grid_color (Optional[str]) – the color of the grid lines
tick_color (Optional[str]) – the color of the ticks
tick_label_color (Optional[str]) – the color of the tick labels
legend_border_color (Optional[str]) – color of the legend border
legend_background_color (Optional[str]) – color of the legend background

Returns

self

set_font(family=None, cursive=None, fantasy=None, monospace=None, sans_serif=None, serif=None, size=None, style=None, variant=None, weight=None)[source]

Set font styling options.

Parameters

family (Optional[str]) – font family to use, can be {}, default: sans-serif
cursive (Optional[Union[str, List[str]]]) – which font(s) to use for cursive text
fantasy (Optional[Union[str, List[str]]]) – which font(s) to use for fantasy text
monospace (Optional[Union[str, List[str]]]) – which font(s) to use for monospace text
sans_serif (Optional[Union[str, List[str]]]) – which font(s) to use for sans-serif text
serif (Optional[Union[str, List[str]]]) – which font(s) to use for serif text
size (Optional[Union[float, int]]) – base font size in pt that all other elements scale relative to, default: 10.0
style (Optional[str]) – font style, can be {“normal”, “roman”, “italic”, “oblique”}, default: normal
variant (Optional[str]) – font variant, can be {“normal”, “small-caps”}, default: normal
weight (Optional[Union[float, int, str]]) – font weight, can be {“ultralight”, “light”, “normal”, “regular”, “book”, “medium”, “roman”, “semibold”, “demibold”, “demi”, “bold”, “heavy”, “extra bold”, “black”}, default: normal

Returns

self

set_grid(draw=None, axis=None, ticks=None, alpha=None, style=None, width=None)[source]

Set grid styling options.

Parameters

draw (Optional[bool]) – True if grid should be drawn, False otherwise, default: False
axis (Optional[str]) – axes along which the grid should be drawn, can be {“both”, “x”, “y”}, default: “both”
ticks (Optional[str]) – which tick level to base the grid on, can be {“major”, “minor”, “both”}, default: “major”
alpha (Optional[float]) – the alpha level to draw the grid with, can be float between 0 and 1, default: 1.0
style (Optional[str]) – the line style to draw the grid with, can be {“-”, “–”, “-.”, “:”, “”}, default: “-”
width (Optional[float]) – the line width to draw the grid with in pt, default: 0.8

Returns

self

set_legend(location=None, round=None, shadow=None, title_size=None, text_size=None, alpha=None, marker_scale=None, padding=None, margin=None, spacing=None)[source]

Set legend styling options.

Parameters

location (Optional[str]) – The location of the legend. Can be {‘best’, ‘upper right’, ‘upper left’, ‘lower left’, ‘lower right’, ‘right’, ‘center left’, ‘center right’, ‘lower center’, ‘upper center’, ‘center’} or a 2-tuple giving the coordinates of the lower-left corner. Default: ‘best’
round (Optional[bool]) – indicates if legend corners should be rounded or rectangular. Default: True
shadow (Optional[bool]) – indicates if the legend should cast a shadow. Default: False
title_size (Optional[str]) – font size of the legend title, can be {“xx-small”, “x-small”, “small”, “medium”, “large”, “x-large”, “xx-large”}, default: “medium”
text_size (Optional[str]) – font size of the legend title, can be {“xx-small”, “x-small”, “small”, “medium”, “large”, “x-large”, “xx-large”}, default: “medium”
alpha (Optional[float]) – transparency of the legend patch.
marker_scale (Optional[float]) – the relative size of legend markers. Default: 1.0
padding (Optional[Union[float, int]]) – space between legend border and legend content in pt. Default: 0.4
margin (Optional[Union[float, int]]) – space between legend border and axes in pt. Default: 0.5
spacing (Optional[Union[float, int]]) – spacing of legend elements in pt. Default: 0.5

Returns

self

set_lines(style=None, width=None)[source]

Set line styling options.

Parameters

style (Optional[str]) – the style to draw lines with, can be {“-”, “–”, “-.”, “:”, “”}, default: “-”
width (Optional[float]) – the width to draw lines with in pt, default: 1.5

Returns

self

set_overrides(rc)[source]

Set custom overrides of rcparam parameters directly

Parameters: rc (dict) – Dict of valid matplotlib rcparams
Returns: self

set_tick_labels(location=None, size=None, left=None, right=None, bottom=None, top=None)[source]

Set tick label styling options.

Parameters

location (Optional[str]) – location of the tick labels, can be {“left”, “right”, “bottom”, “top”, “center”}, default: center
size (Optional[str]) – size of the tick label, can be {“xx-small”, “x-small”, “small”, “medium”, “large”, “x-large”, “xx-large”}, default: “normal”
left (Optional[bool]) – whether to draw the tick labels to the left of the y-axis, default: True
right (Optional[bool]) – whether to draw the tick labels to the right of the y-axis, default: False
bottom (Optional[bool]) – whether to draw the tick labels at the bottom of the x-axis, default: True
top (Optional[bool]) – whether to draw the tick labels at the top of the x-axis, default: False

Returns

self

set_ticks(x_align=None, y_align=None, direction=None, draw_minor=None, width_major=None, width_minor=None, size_major=None, size_minor=None, pad_major=None, pad_minor=None)[source]

Set styling options for ticks.

Parameters

x_align (Optional[str]) – alignment of ticks along the horizontal axes, can be {“center”, “right”, “left”}, default: “center”
y_align (Optional[str]) – alignment of ticks along the vertical axes, can be {“center”, “top”, “bottom”, “baseline”, “center_baseline”}, default: “center_baseline”
direction (Optional[str]) – direction the ticks should be facing, can be {“in”, “out”, “inout”}, default: “out”
draw_minor (Optional[bool]) – whether to draw minor ticks, default: False
width_major (Optional[Union[float, int]]) – width of major ticks in pt, default: 0.8
width_minor (Optional[Union[float, int]]) – width of minor ticks in pt, default: 0.6
size_major (Optional[Union[float, int]]) – size of major ticks in pt, default: 3.5
size_minor (Optional[Union[float, int]]) – size of minor ticks in pt, default: 2
pad_major (Optional[Union[float, int]]) – padding of major ticks in pt, default: 3.5
pad_minor (Optional[Union[float, int]]) – padding of minor ticks in pt, default: 3.4

Returns

self

set_title(location=None, size=None, weight=None, pad=None)[source]

Sets title styling options.

Parameters

location (Optional[str]) – the location of the title, one of {left, right, center} default: ‘center’
pad (Optional[float]) – pad between axes and title in pt, default: 6.0
size (Optional[Union[float, str]]) – the font size of the title, float or one of {‘xx-small’, ‘x-small’, ‘small’, ‘medium’, ‘large’, ‘x-large’, ‘xx-large’}, default: ‘large’
weight (Optional[Union[float, int, str]]) – the font weight of the title, int in range 0-1000 or one of {‘ultralight’, ‘light’, ‘normal’, ‘regular’, ‘book’, ‘medium’, ‘roman’, ‘semibold’, ‘demibold’, ‘demi’, ‘bold’, ‘heavy’, ‘extra bold’, ‘black’}, default: “normal”

Returns

self

set_transforms(trim=None, offset=None, rotate_xlabel=None, rotate_ylabel=None)[source]

Set the transforms

Parameters

trim (Optional[bool]) – trims the axes to the nearest major tick, can be {“x”, “y”, “both”}
offset (Optional[int]) – offset shift of the axes in pt. Applies to all axes
rotate_xlabel (Optional[int]) – rotation of x-axis labels in degrees
rotate_ylabel (Optional[int]) – rotation of y-axis labels in degrees
log_axes – set log scale for the specified axes, can be {‘both’, ‘x’, ‘y’}

Returns

self

Transforms

aquarel.transforms.offset(distance)[source]

Offsets the plot spines. Code partly taken from https://github.com/mwaskom/seaborn/blob/563e96d3be1eaee8db8dfbccf7eed1f1c66dfd31/seaborn/utils.py#L292

Parameters: distance (int) – offset distance int pt.

aquarel.transforms.rotate_xlabel(degrees)[source]

Rotates the x-labels of the current plot.

Parameters: degrees (int) – rotation in degrees

aquarel.transforms.rotate_ylabel(degrees)[source]

Rotates the y-labels of the current plot.

Parameters: degrees (int) – rotation in degrees

aquarel.transforms.trim(axis)[source]

Trims axes of a plot to first and last major tick. Code partly taken from https://github.com/mwaskom/seaborn/blob/563e96d3be1eaee8db8dfbccf7eed1f1c66dfd31/seaborn/utils.py#L292

Parameters: axis (str) – axes to apply the trim to. Can be {“x”, “y”, “both”}.

Utils

aquarel.utils.list_themes()[source]

Returns a list of available theme names.

Returns: a list of available theme names

aquarel.utils.load_theme(theme_name)[source]

Sets the chosen style and color palette globally.

Parameters: theme_name (str) – name of the theme to load
Returns: the specified Theme
Raises: ValueError – if a theme is not found

aquarel.utils.make_samples()[source]: Generates sample plots for all themes to be used in documentation