palette
plot.palette
Named colour roles for figures, so a project’s colours live in one file.
A style sheet carries only what matplotlib has an rcParam for. That covers the cycler and the ink, and stops short of the roles a figure actually reasons in: the one colour that means this is the point, the neutral that everything unlabelled is drawn in, the hairline grey behind it. Those live here, in the theme a figure declares (theme: {iri: tvbo:theme/default}, or a document of its own), so changing a project’s colours is one edit and every panel follows. A colour is never a style layer: Figure.style carries the looks TVB-O does not own, and the theme is applied over all of them.
The cycler is [base] + palette: a plot that names no colour comes out in the neutral, and only a panel that means to separate conditions reaches into the hues. highlight is deliberately outside the cycle, because a colour that is handed to the second line of every plot cannot also mean emphasis.
Continuous scales live here too, under colormaps, so the two kinds of colour move together and a figure never names a colormap of its own: anything categorical takes a hue from palette, anything ordinal or continuous takes a colormap role, and an ordinal scale drawn as discrete swatches samples one with :func:ramp rather than picking hues that imply no order.
TVB-O’s own colours are :data:PATH, the curated tvbo:theme/default shipped in tvbo/database/themes/, and it is what :data:DEFAULT reads and what a project’s file falls back to role by role. It is a Theme in the figure spec (schema/figure.yaml), so it validates like any other TVB-O document and so a consumer outside Python — the documentation site’s stylesheet, the manuscript’s figures — reads those hexes rather than keeping a copy that drifts.
Attributes
| Name | Description |
|---|---|
| DEFAULT | TVB-O’s own colours: the base every figure resolves a role against, whether or not it declared a theme. |
| DEFAULT_GEOMETRY | The geometry the curated theme fixes, the same base for the other half of the look. Read here rather than in the adapter, because the file it comes from is this module’s. |
| FIELDS | |
| GEOMETRY | The Theme slots that are not colours. Named here so a theme file can be read for its colours without its geometry being reported as a typo; tests/test_plot_palette.py pins the tuple to the schema so the two cannot drift. |
| GUARANTEED_COLORMAPS | |
| PATH | |
| ROLES |
Functions
| Name | Description |
|---|---|
| as_color | value as a colour: a palette role or hue if it names one, otherwise itself. |
| as_colormap | value as a colormap name: a palette key if it names one, otherwise itself. |
| background | The page the figure is printed on. |
| base | Standard lines, bars and markers, wherever the colour carries no meaning. |
| color | One colour by role name, or by palette.<index> for a hue. |
| colormap | The colormap this project gives role — the one continuous scale a panel is allowed to use. |
| current | The palette in force, as a plain dict. |
| cycle | What axes.prop_cycle is set to: the neutral first, then the hues. |
| highlight | The single emphasis colour, kept out of the cycle so it never lands on a panel by accident. |
| ink | Text, spines and ticks: the near-black everything is read against. |
| load | Read and validate a palette, from a YAML path or a mapping already in hand. |
| muted | Hairlines and de-emphasised strokes: present, and not competing. |
| palette | The categorical hues, cycled to n entries when a panel needs a fixed number of them. |
| ramp | n colours sampled across a colormap, for an ordinal scale drawn as discrete swatches. |
| use | Make source the current palette and put its colours into the rcParams that carry them. |
as_color
plot.palette.as_color(value)value as a colour: a palette role or hue if it names one, otherwise itself.
The one place a declared colour is turned into a drawn one. A role (highlight) or a hue (palette.2) resolves against the palette in force; a hex, a backend colour name, a sequence, or None passes through untouched, so a spec written before the palette existed keeps drawing exactly as it did. Resolution happens here rather than at generation time so an emitted script that swaps its palette recolours with it.
as_colormap
plot.palette.as_colormap(value, default='sequential')value as a colormap name: a palette key if it names one, otherwise itself.
A key the project declared (diverging, or its own meg) resolves to whatever that key holds; anything else is left for the backend’s own registry, so cividis and parula are untouched. None takes default, which is how an undeclared mark ends up on the project’s scale instead of the backend’s.
background
plot.palette.background()The page the figure is printed on.
base
plot.palette.base()Standard lines, bars and markers, wherever the colour carries no meaning.
color
plot.palette.color(name)One colour by role name, or by palette.<index> for a hue.
colormap
plot.palette.colormap(role='sequential')The colormap this project gives role — the one continuous scale a panel is allowed to use.
current
plot.palette.current()The palette in force, as a plain dict.
cycle
plot.palette.cycle()What axes.prop_cycle is set to: the neutral first, then the hues.
highlight
plot.palette.highlight()The single emphasis colour, kept out of the cycle so it never lands on a panel by accident.
ink
plot.palette.ink()Text, spines and ticks: the near-black everything is read against.
load
plot.palette.load(source)Read and validate a palette, from a YAML path or a mapping already in hand.
A file is read through TVBO’s own loader, so a palette takes !include and merge keys like every other TVBO document and may name its class in the usual envelope.
muted
plot.palette.muted()Hairlines and de-emphasised strokes: present, and not competing.
palette
plot.palette.palette(n=None)The categorical hues, cycled to n entries when a panel needs a fixed number of them.
ramp
plot.palette.ramp(n, role='sequential', lo=0.15, hi=0.75)n colours sampled across a colormap, for an ordinal scale drawn as discrete swatches.
A ladder of rungs or a set of ordered bins is not categorical: hues from the palette would say the classes are unrelated, when the whole point is that they are ordered. The ends are trimmed by default, because a scale that runs into the colormap’s near-black and near-white loses its extremes against the page.
use
plot.palette.use(source)Make source the current palette and put its colours into the rcParams that carry them.