plotnine.themes.themeable.themeable

themeable(theme_element)

Abstract class of things that can be themed.

Every subclass of themeable is stored in a dict at register with the name of the subclass as the key.

It is the base of a class hierarchy that uses inheritance in a non-traditional manner. In the textbook use of class inheritance, superclasses are general and subclasses are specializations. In some since the hierarchy used here is the opposite in that superclasses are more specific than subclasses.

It is probably better to think if this hierarchy of leveraging Python’s multiple inheritance to implement composition. For example the axis_title themeable is composed of the x_axis_title and the y_axis_title. We are just using multiple inheritance to specify this composition.

When implementing a new themeable based on the ggplot2 documentation, it is important to keep this in mind and reverse the order of the “inherits from” in the documentation.

For example, to implement,

axis_title_x - x axis label (element_text; inherits from axis_title)
axis_title_y - y axis label (element_text; inherits from axis_title)

You would have this implementation:

class axis_title_x(themeable):
    ...

class axis_title_y(themeable):
    ...

class axis_title(axis_title_x, axis_title_y):
    ...

If the superclasses fully implement the subclass, the body of the subclass should be “pass”. Python(mro) will do the right thing.

When a method does require implementation, call super() then add the themeable’s implementation to the axes.

Notes

A user should never create instances of class Themeable or subclasses of it.

Attributes

Name	Description
properties	Return only the properties that can be applied
rcParams	Return themeables rcparams to an rcparam dict before plotting.

properties

properties

Return only the properties that can be applied

rcParams

rcParams : dict[str, Any]

Return themeables rcparams to an rcparam dict before plotting.

Returns

dict: Dictionary of legal matplotlib parameters.
This method should always call super(…).rcParams and
update the dictionary that it returns with its own value, and
return that dictionary.
This method is called before plotting. It tends to be more
useful for general themeables. Very specific themeables
often cannot be be themed until they are created as a
result of the plotting process.

Methods

Name	Description
apply	Called by the theme to apply the themeable
apply_ax	Called after a chart has been plotted.
apply_figure	Apply theme to the figure
blank_ax	Blank out theme elements
blank_figure	Blank out elements on the figure
from_class_name	Create a themeable by name
is_blank	Return True if theme_element is made of element_blank
merge	Merge properties of other into self

apply

apply(theme)

Called by the theme to apply the themeable

Subclasses should not have to override this method

apply_ax

apply_ax(ax)

Called after a chart has been plotted.

Subclasses can override this method to customize the plot according to the theme.

This method should be implemented as super().apply_ax() followed by extracting the portion of the axes specific to this themeable then applying the properties.

Parameters

ax : matplotlib.axes.Axes

apply_figure

apply_figure(figure, targets)

Apply theme to the figure

blank_ax

blank_ax(ax)

Blank out theme elements

blank_figure

blank_figure(figure, targets)

Blank out elements on the figure

from_class_name

from_class_name(name, theme_element)

Create a themeable by name

Parameters

name : str: Class name
theme_element : element object: An element of the type required by the theme. For lines, text and rects it should be one of: element_line, element_rect, element_text or element_blank

Returns

out : plotnine.themes.themeable.themeable

is_blank

is_blank()

Return True if theme_element is made of element_blank

merge

merge(other)

Merge properties of other into self

Raises

ValueError: If any of the properties are blank