Styling#

See also the Styles page for an introduction to styles in iplotx. See also Complete style specification.

Functions#

iplotx.style.context(style: str | dict[str, Any] | Sequence[str | dict[str, Any]] | Iterable[str | dict[str, Any]] | None = None, **kwargs)[source]#

Create a style context for iplotx.

Parameters:

  • style – A single style specification or a list of style specifications, which are then applied in order. Each style can be a string (for an existing style) or a dictionary with the elements that are to change.

  • **kwargs – Additional style changes to be applied at the end of all styles.

Yields:

A context manager that applies the style and reverts it back to the previous one upon exit.

iplotx.style.use(style: str | dict[str, Any] | Sequence[str | dict[str, Any]] | Iterable[str | dict[str, Any]] | None = None, **kwargs)[source]#

Use iplotx style setting for a style specification.

The style name of ‘default’ is reserved for reverting back to the default style settings.

Parameters:

  • style – A style specification, currently either a name of an existing style or a dict with specific parts of the style to override. The string “default” resets the style to the default one. If this is a sequence, each style is applied in order.

  • **kwargs – Additional style changes to be applied at the end of any style.

iplotx.style.reset() → None[source]#

Reset to default style.

iplotx.style.get_style(name: str = '', *args) → dict[str, Any][source]#

Get a deep copy of the chosen style.

Parameters:

  • name – The name of the style to get. If empty, the current style is returned. Substyles can be obtained by using a dot notation, e.g. “default.vertex”. If “name” starts with a dot, it means a substyle of the current style.

  • *args – A single argument is accepted. If present, this value (usually a dictionary) is returned if the queried style is not found. For example, get_style(“.nonexistent”) raises an Exception but get_style(“nonexistent”, {}) does not, returning an empty dict instead.

Returns:

The requected style or substyle.

NOTE: The deep copy is a little different from standard deep copies. Here, keys

(which need to be hashables) are never copied, but values are. This can be useful for hashables that change hash upon copying, such as Biopython’s tree nodes.

The following functions are reported for completeness but are rarely used by users directly:

iplotx.style.unflatten_style(style_flat: dict[str, str | dict | int | float]) → None[source]#

Convert a flat or semi-flat style into a fully structured dict.

Parameters:

style_flat – A flat dictionary where keys may contain underscores, which are taken to signify subdictionaries.

NOTE: The dict is changed in place.

Example

>>> style = {'vertex_size': 20}
>>> unflatten_style(style)
>>> print(style)
{'vertex': {'size': 20}}
iplotx.style.rotate_style(style: dict[str, Any], index: int | None = None, key: Hashable | None = None, key2: Hashable | None = None, props: Sequence[str] | None = None) → dict[str, Any][source]#

Rotate leaves of a style for a certain index or key.

Parameters:

  • style – The style to rotate.

  • index – The integer to rotate the style leaves into.

  • key – For dict-like leaves (e.g. vertex properties specified as a dict-like object over the vertices themselves), the key to use for rotation (e.g. the vertex itself).

  • key2 – For dict-like leaves, a backup key in case the first key fails. If this is None or also a failure (i.e. KeyError), default to the empty type constructor for the first value of the dict-like style leaf.

  • props – The properties to rotate, usually all leaf properties.

Returns:

A style with rotated leaves, which describes the properties of a single element (e.g. vertex).

Example

>>> style = {'vertex': {'size': [10, 20]}}
>>> rotate_style(style, index=0)
{'vertex': {'size': 10}}