Skip to content
API Reference
core
theme
Theme

Theme

Mojo struct 🡭

Theme

@memory_only
struct Theme

Fields

  • background (Color): The canvas’s fill color, drawn behind everything else.
  • mark_color (Color): The default ink a mark draws in – bar fill, line stroke, point fill, … – whenever no data-driven color/color_categories channel or per-mark override (mark_color_negative, a palette, …) applies instead.
  • axis_color (Color): The axis line/tick/frame color.
  • gridline_color (Color): Gridline color, drawn when show_gridlines is True.
  • text_color (Color): The default text color – tick labels, the chart title, and anywhere else no more specific color field (subtitle_color, annotation_color, …) applies.
  • font_size (Float64): The base font size, in points, for tick/legend labels – scaled by Theme.scale the same as every other pixel-sized quantity (see _Scaled’s docstring, text.mojo).
  • point_radius (Float64): The default pixel radius for Mark.POINT/EFFECT_SCATTER markers, before any data-driven size channel overrides it.
  • line_width (Float64): The default stroke width, in pixels, for Mark.LINE/AREA and every other stroked mark.
  • margin_left (Int): Reserved pixel space along the plot’s left edge, before the y-axis’s own tick-label width/margin_buffer are added on top.
  • margin_right (Int): Reserved pixel space along the plot’s right edge, before a legend’s own reserved width (if any) is added on top.
  • margin_top (Int): Reserved pixel space along the plot’s top edge, before a title/subtitle’s own reserved height (if any) is added on top.
  • margin_bottom (Int): Reserved pixel space along the plot’s bottom edge, before an x-axis title’s own reserved height (if any) is added on top.
  • show_gridlines (Bool): Whether to draw gridlines at all; defaults to True.
  • show_minor_ticks (Bool): Whether to draw a short tick mark at each minor tick; defaults to False, so no existing chart changes. Separate from show_minor_gridlines: a minor level on the axis and a minor level across the plot are different amounts of ink, and a log axis often wants the first without the second.
  • show_minor_gridlines (Bool): Whether to draw a gridline at each minor tick as well; defaults to False, so nothing moves for a theme that does not ask. Ignored when show_gridlines is off – minor gridlines under no major ones would be a grid with no reference points. Minor ticks themselves are drawn whenever the axis has them, since a short mark on the axis costs nothing and a gridline across the plot does.
  • minor_gridline_color (Color): The color minor gridlines are stroked in. Lighter than gridline_color by default: a minor level in the same color makes a chart busier rather than more readable, since the eye can no longer tell which lines carry the labeled values.
  • minor_tick_length (Int): Pixel length of a minor tick mark, before scale. Shorter than tick_length so the labeled ticks stay the ones that read as structure.
  • color_scale_low (Color): The low end of the default continuous color gradient (Plot. encode(color=...), Mark.HEATMAP/CORRPLOT/CALENDAR_HEATMAP).
  • color_scale_mid (Color): The midpoint of the default continuous color gradient, a deliberate third stop; see the module docstring.
  • color_scale_high (Color): The high end of the default continuous color gradient.
  • color_ramp (ColorRamp): A continuous gradient given as many stops instead of three, spread evenly over [0, 1] by ColorScale.from_theme. Empty by default, which leaves color_scale_low/mid/high in charge; setting it overrides all three. Three stops are enough for a diverging scale, where the middle is a real feature of the data. They are not enough for a perceptually uniform sequential map – viridis and its family are defined by many stops precisely because that is what makes equal steps in the value look like equal steps in color, and interpolating three of them throws the property away. See dataviz.core.colormaps for the standard ones.
  • categorical_palette (ColorPalette): The colors a multi-series or category-colored chart cycles through – grouped and stacked bars, streamgraphs, pies, sunbursts, categorical scatter colors and the rest. Empty by default, meaning default_categorical_palette()’s eight Okabe-Ito colors. Named alternatives live in dataviz.core.palettes. Set it to make a preset’s multi-series charts read on a given ground or in grayscale: print_safe() uses a lightness-ordered set of grays so a photocopy still tells series apart (#426). Plot.color_map() still overrides individual categories by name.
  • size_range_min (Float64): The smallest pixel radius a data-driven size channel maps its column’s minimum value to.
  • size_range_max (Float64): The largest pixel radius a data-driven size channel maps its column’s maximum value to.
  • show_legend (Bool): Whether to draw a legend at all, for every mark that has one; defaults to True.
  • scale (Float64): Uniformly multiplies every other pixel-sized quantity render() computes (font size, margins, point radius, line width, tick length, legend layout, …); see this struct’s own module docstring for the full HiDPI-rendering reasoning.
  • raster_supersample (Int): How many times larger than the requested size render()/ render_facets()/render_layers() draw at internally before downsampling back down, for finer anti-aliasing at shape edges. Defaults to 0, meaning automatic: the factor is chosen per mark by _auto_supersample() from each mark type’s straight_edged constant, which is the list of record. It is 1 for the marks drawn entirely from straight-edged geometry – rectangles and polygons, so bars, boxes, heatmaps, lines, areas, and also violins and radars, whose curved look is a polygon through many points – and 3 for the marks that draw circles, arcs or curved strokes, such as points, pie and polar. A non-zero line_smoothing forces 3 whatever the mark, since a smoothed line is a curve however it is named. Setting a value here overrides all of that.

Composes multiplicatively with scale and is not a substitute for it: scale changes the logical pixel size of everything drawn (fonts, margins, line widths, …) for HiDPI output, while this only controls how much extra antialiasing work a raster render pays before shrinking back to that logical size. render_svg()/render_facets_svg()/render_layers_svg() ignore it entirely, since vector output has no downsample step.

Set 1 to disable supersampling outright, for exact single-pixel raster output in a test. That lowers the factor for the curved marks only; the straight-edged ones are already at 1, so it changes nothing for them. A set value must be >= 1, checked where it is read (render()/ render_facets()/render_layers()) rather than eagerly here, matching line_smoothing’s deferred-to-render-time validation; the 0 that selects automatic is exempt.

  • color_by_sign (Bool): Whether Mark.BAR colors each bar by whether its value is negative (mark_color_negative) or not (mark_color); defaults to False (every bar stays mark_color).
  • mark_color_negative (Color): The ink for a negative value – Mark.BAR when color_by_sign is True, and unconditionally for Mark.WATERFALL/CANDLESTICK, whose falling/down coloring isn’t optional.
  • bullet_range_color_light (Color): The lightest end of Mark.BULLET’s grayscale qualitative-range band gradient (lowest range index).
  • bullet_range_color_dark (Color): The darkest end of Mark.BULLET’s grayscale qualitative-range band gradient (highest range index).
  • waterfall_total_color (Color): Mark.WATERFALL’s color for a row encode_waterfall()’s is_total marks as a running-total checkpoint, distinct from mark_color/ mark_color_negative.
  • radialbar_track_color (Color): The unfilled background track Mark.RADIALBAR sweeps its rings over.
  • treemap_label_color (Color): The label color drawn on a Mark.TREEMAP leaf rectangle.
  • radar_fill_alpha (UInt8): The opacity of each Mark.RADAR series’ filled polygon; outlines stay opaque so overlapping series remain individually traceable.
  • sankey_flow_alpha (UInt8): The opacity of Mark.SANKEY flow ribbons; nodes stay opaque so flows remain visible where crossing ribbons overlap.
  • shape_by_category (Bool): Whether Mark.POINT/SINGLE_AXIS/EFFECT_SCATTER draws each color_categories row with a distinct point shape (PointShape, marker.mojo) on top of its color, cycling default_marker_shapes() the same % len way the palette cycles. Defaults to False. A no-op without color_categories. Redundant coding for charts viewed without reliable color: a legend row’s shape and color identify the same category.
  • fill_pattern_by_category (Bool): Whether the marks that fill one shape per category or series (Mark.ARC, STACKED_BAR, GROUPED_BAR, FUNNEL, STREAMGRAPH, TREEMAP, MARIMEKKO, NIGHTINGALE, POLAR_BAR, POPULATION_PYRAMID, SUNBURST) draw a HatchStyle pattern over each fill, dealt by the same index as its color, legend swatches included (#842). Defaults to False. shape_by_category’s counterpart for fills: a grayscale printout or a reader with a color-vision deficiency can still tell the series apart. The first category stays solid.
  • line_smoothing (Float64): How much Mark.LINE/AREA curves through its data points, via a Catmull-Rom-derived spline – 0.0 (the default) draws plain straight segments; 1.0 the full curve; must be in [0.0, 1.0]. Mutually exclusive with a step interpolation (Plot.mark_line(step=...)/mark_area(step=...)/ mark_streamgraph(step=...)): both together raise at render time (_check_step_smoothing, validate.mojo), since smoothing rounds off the corners a step exists to draw. See StepStyle for why there is no sensible middle ground to fall back to.
  • title_font_size (Float64): The chart title’s font size, in points; 18.0 against font_size’s 12.0 for tick/legend labels, scaled by scale like every other size.
  • subtitle_font_size (Float64): The subtitle’s font size, in points – the same size an axis title uses, both reading as a subordinate label under the title.
  • subtitle_color (Color): The subtitle’s dedicated color, distinct from text_color so it recedes as supporting context rather than competing with the title.
  • axis_title_font_size (Float64): The x/y-axis title’s font size, in points.
  • annotation_color (Color): Plot.annotate_line()/annotate_vline()/annotate_point()/ annotate_best_fit()’s color, for the mark and its label. Distinct from mark_color (an annotation is not data) and from axis_color/ gridline_color (it should read as more present than chrome).
  • annotation_area_color (Color): Plot.annotate_area()/annotate_band()’s fill, with real alpha (a=200) so the mark underneath shows through; both canvas backends composite Color.a. Label text still uses annotation_color.
  • show_axis_left (Bool): Draw the left axis line. On by default. The four show_axis_* flags are the spine controls #346 asked for: all four off is a frameless chart, all four on is the full box several journal styles want, and turning off the top and right is the default here.

Hiding an axis hides its tick marks too, since a tick with no line to sit on reads as a stray hairline. Tick labels stay: they carry the numbers, and a frameless chart is meant to have less furniture, not less information.

The left and right lines are drawn only when the mark has a y-axis at all; Mark.RUG and friends suppress it whatever these say.

  • show_axis_right (Bool): Draw the right axis line. Off by default. See show_axis_left.
  • show_axis_top (Bool): Draw the top axis line. Off by default. See show_axis_left.
  • show_axis_bottom (Bool): Draw the bottom axis line. On by default. See show_axis_left.
  • x_axis_position (AxisPosition): Where the horizontal (x) axis line sits: AxisPosition.EDGE (the bottom of the plot rect, the default) or ZERO (at y = 0, crossing the data). ZERO is the one spine setting that changes meaning rather than appearance: with data spanning zero, an axis at the edge makes a value’s sign something you read off a label, and an axis through zero makes it something you see. The x tick marks and their labels move with the line, which is why the labels can land on top of the data; that is left to the caller.

Only continuous-axis marks honor it; see AxisPosition.ZERO for the fallback rule.

  • y_axis_position (AxisPosition): Where the vertical (y) axis line sits: AxisPosition.EDGE (the left of the plot rect, the default) or ZERO (at x = 0). See x_axis_position.
  • histogram_edge_color (Color): Mark.HISTOGRAM’s separator between two adjacent nonempty bins: one pixel column, the last of the left bin, from the baseline to the shorter of the two. Defaults to white, the default background, so it reads as a hairline gap; set it to a dark theme’s background for the same effect there, or to a transparent color (a=0) for none.
  • font_family (String): Every _TextRequest’s typeface; defaults to "sans-serif", a generic keyword both the raster (fontconfig) and SVG (CSS) text backends resolve consistently.
  • title_bold (Bool): Whether the chart title draws bold; defaults to True. The one field whose default affects existing renders; see the module docstring.
  • halo_alpha (UInt8): The opacity Mark.EFFECT_SCATTER blends each point’s halo at before flattening it against white (_lighten, continuous.mojo).
  • tick_length (Int): The pixel length of each axis tick mark.
  • label_gap (Int): The pixel gap between a tick mark and its label.
  • legend_width (Int): The reserved pixel width for a legend’s swatch-plus-label column, when its dynamic width can’t be computed some other way.
  • legend_swatch_size (Int): The pixel size of each legend entry’s color swatch.
  • legend_row_gap (Int): The pixel gap between consecutive legend entries.
  • continuous_legend_bar_width (Int): The pixel width of a continuous (gradient) legend’s color bar.
  • continuous_legend_bar_height (Int): The pixel height of a continuous (gradient) legend’s color bar.
  • margin_buffer (Int): Extra breathing-room padding, in pixels, added after a margin’s own tick-label-width/tick-length/label-gap computation.
  • error_bar_cap_width (Float64): Half the pixel width of the horizontal cap Plot.encode()’s y_err channel draws at each end of an error bar. Mark.BOX’s whisker caps are sized from the band width instead.
  • output_format (OutputFormat): The file format save() (rendering.mojo) writes when given a Plot and a path; defaults to OutputFormat.SVG. render()/render_svg() ignore this field.
  • tooltips (Tooltips): Whether each datum gets an SVG <title>, which a browser shows as a hover tooltip: Tooltips.AUTO by default, which draws them on a plot that would draw at most auto_tooltip_limit and none above (tooltips.mojo). Plot.tooltips() overrides it for one chart. A no-op on the raster and PDF backends. Emitted through DrawTarget.begin_annotated_group/ end_annotated_group (canvas_mojo >= 0.13.0), so one datum’s primitives (a box plot’s box, whiskers, caps and median) share one tooltip. SvgCanvas turns that into <g><title>...</title>...</g>; Canvas ignores both calls. Titles are XML-escaped by canvas_mojo.

Which marks honor it is MarkType.supports_tooltips (mark_type.mojo), the one table the docs’ feature-support page is generated from. Where a mark encodes more than one number, the title carries all of them rather than picking one – a bullet row’s measure and target, a candle’s four prices, a span’s two ends – since that combination is what the shape says. Tooltips.ON on a mark without tooltips raises when the chart renders.

  • auto_tooltip_limit (Int): The most tooltips Tooltips.AUTO draws on one plot; above it, AUTO draws none. AUTO_TOOLTIP_LIMIT (1,000) by default, which tooltips.mojo explains. Raise it for a large chart whose points a reader still needs to hover one at a time; Tooltips.ON ignores it altogether.
  • missing (Missing): What a mark does with a missing observation, carried as NaN (missing.mojo). Missing.DRAW by default: a line breaks at the gap, a point is not drawn, a statistic uses what is there. Missing.RAISE refuses any missing value at encode time, which is what this package did before #367. Infinity is refused either way.
  • missing_category_label (String): What an absent category is called when missing is Missing.DRAW; “(missing)” by default. A missing category is a label, not a measurement: the rows are kept and gathered under this name, in the position where the first of them appeared. A missing value has no such reading and drops out instead – see Missing (missing.mojo).
  • show_data_labels (Bool): Whether a mark draws each value as text, in text_color at font_size; defaults to False. Which marks honor it is MarkType.supports_data_labels (mark_type.mojo); rendering any other mark with it on raises, rather than drawing no labels and saying nothing (#676). Formatted via _label_decimals() (scale.mojo), the fewest decimal places that represent the value exactly, rather than the y-axis’s coarser Ticks.decimals. A Theme flag rather than an encode() channel, like color_by_sign.
  • gridline_style (LineStyle): How gridlines are stroked. SOLID by default, which is what they have always been; DOTTED is the common house style and keeps them from competing with the data.
  • annotation_arrow_width (Float64): Stroke width of an annotate_arrow() shaft, in pixels before scale. Slightly heavier than a gridline by default: an arrow is an assertion the author is making about the data, not chrome, and it has to read as deliberate against whatever it crosses. The head is sized from scale alone – see _ARROW_HEAD_LENGTH (annotations.mojo).
  • annotation_line_style (LineStyle): How annotate_hline/annotate_vline/annotate_best_fit are stroked. SOLID by default. Dashing these is the conventional way to say a reference line or a fitted trend is not a measurement – see LineStyle.
  • legend_position (LegendPosition): Which edge of the plot area the legend is reserved on and drawn against; defaults to RIGHT. RIGHT/LEFT cost plot width, TOP/BOTTOM cost plot height and lay entries out along a row – wrapping rows for a categorical legend, and side-by-side sections for a point mark’s continuous color bar and size circles. Ignored when show_legend is off, and by any mark that draws no legend. See LegendPosition.

One exception: render_layers()/render_facets() take a column on either side and fall back from TOP/BOTTOM to RIGHT. A layered chart stacks a per-layer point legend under the series legend, and there is no row form of that stack; LEFT works there as elsewhere.

  • x_label_rotation (XAxisLabelRotation): Whether/how far _draw_categorical_axis_frame’s x-axis tick labels rotate when they would otherwise overlap; see XAxisLabelRotation’s own docstring. Defaults to AUTO.
  • x_tick_format (TickFormat): How the x-axis’s own tick labels render; see TickFormat’s own docstring for the available kinds. Defaults to AUTO, matching Ticks.labels()’s default behavior. Log-axis ticks (Plot.scale_x_log()) aren’t covered yet – see Ticks.labels().
  • y_tick_format (TickFormat): x_tick_format’s y-axis counterpart. Also what show_data_labels formats a value with (the x-axis’s own format for a horizontal=True categorical mark, whichever axis is the value axis there), and what a continuous color/size legend’s endpoint labels use.

Implemented traits

AnyType, Copyable, Deinitable, ImplicitlyCopyable, Movable

Methods

__init__ 

fn def __init__(out self, background: Color = WHITE, mark_color: Color = Color(UInt8(30), UInt8(100), UInt8(180), UInt8(255)), axis_color: Color = Color(UInt8(80), UInt8(80), UInt8(80), UInt8(255)), gridline_color: Color = Color(UInt8(225), UInt8(225), UInt8(225), UInt8(255)), text_color: Color = Color(UInt8(40), UInt8(40), UInt8(40), UInt8(255)), font_size: Float64 = 12, point_radius: Float64 = 3.5, line_width: Float64 = 2, margin_left: Int = Int(60), margin_right: Int = Int(20), margin_top: Int = Int(20), margin_bottom: Int = Int(50), show_gridlines: Bool = True, show_minor_ticks: Bool = False, show_minor_gridlines: Bool = False, minor_gridline_color: Color = Color(UInt8(240), UInt8(240), UInt8(240), UInt8(255)), minor_tick_length: Int = Int(3), color_scale_low: Color = Color(UInt8(60), UInt8(110), UInt8(200), UInt8(255)), color_scale_mid: Color = Color(UInt8(235), UInt8(235), UInt8(235), UInt8(255)), color_scale_high: Color = Color(UInt8(220), UInt8(90), UInt8(40), UInt8(255)), color_ramp: ColorRamp = ColorRamp(), categorical_palette: ColorPalette = ColorPalette(), size_range_min: Float64 = 3, size_range_max: Float64 = 15, show_legend: Bool = True, scale: Float64 = 1, raster_supersample: Int = Int(0), color_by_sign: Bool = False, mark_color_negative: Color = Color(UInt8(200), UInt8(60), UInt8(60), UInt8(255)), bullet_range_color_light: Color = Color(UInt8(224), UInt8(224), UInt8(224), UInt8(255)), bullet_range_color_dark: Color = Color(UInt8(120), UInt8(120), UInt8(120), UInt8(255)), waterfall_total_color: Color = Color(UInt8(100), UInt8(100), UInt8(100), UInt8(255)), radialbar_track_color: Color = Color(UInt8(230), UInt8(230), UInt8(230), UInt8(255)), treemap_label_color: Color = Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), radar_fill_alpha: UInt8 = UInt8(90), sankey_flow_alpha: UInt8 = UInt8(160), shape_by_category: Bool = False, fill_pattern_by_category: Bool = False, line_smoothing: Float64 = 0, title_font_size: Float64 = 18, subtitle_font_size: Float64 = 14, subtitle_color: Color = Color(UInt8(110), UInt8(110), UInt8(110), UInt8(255)), axis_title_font_size: Float64 = 14, annotation_color: Color = Color(UInt8(150), UInt8(150), UInt8(150), UInt8(255)), annotation_area_color: Color = Color(UInt8(224), UInt8(236), UInt8(246), UInt8(200)), histogram_edge_color: Color = Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), show_axis_left: Bool = True, show_axis_right: Bool = False, show_axis_top: Bool = False, show_axis_bottom: Bool = True, x_axis_position: AxisPosition = AxisPosition.EDGE, y_axis_position: AxisPosition = AxisPosition.EDGE, font_family: String = "sans-serif", title_bold: Bool = True, halo_alpha: UInt8 = UInt8(90), tick_length: Int = Int(5), label_gap: Int = Int(4), legend_width: Int = Int(130), legend_swatch_size: Int = Int(14), legend_row_gap: Int = Int(8), continuous_legend_bar_width: Int = Int(14), continuous_legend_bar_height: Int = Int(100), margin_buffer: Int = Int(8), error_bar_cap_width: Float64 = 4, output_format: OutputFormat = OutputFormat.SVG, tooltips: Tooltips = Tooltips.AUTO, missing: Missing = Missing.DRAW, missing_category_label: String = "(missing)", auto_tooltip_limit: Int = Int(1000), show_data_labels: Bool = False, gridline_style: LineStyle = LineStyle.SOLID, annotation_arrow_width: Float64 = 1.5, annotation_line_style: LineStyle = LineStyle.SOLID, legend_position: LegendPosition = LegendPosition.RIGHT, x_label_rotation: XAxisLabelRotation = XAxisLabelRotation.AUTO, x_tick_format: TickFormat = TickFormat.AUTO, y_tick_format: TickFormat = TickFormat.AUTO)

Construct a Theme, overriding any subset of its fields by keyword. Every parameter is one field with the same name and default; see each field’s docstring.

Args:

  • background (Color)
  • mark_color (Color)
  • axis_color (Color)
  • gridline_color (Color)
  • text_color (Color)
  • font_size (Float64)
  • point_radius (Float64)
  • line_width (Float64)
  • margin_left (Int)
  • margin_right (Int)
  • margin_top (Int)
  • margin_bottom (Int)
  • show_gridlines (Bool)
  • show_minor_ticks (Bool)
  • show_minor_gridlines (Bool)
  • minor_gridline_color (Color)
  • minor_tick_length (Int)
  • color_scale_low (Color)
  • color_scale_mid (Color)
  • color_scale_high (Color)
  • color_ramp (ColorRamp)
  • categorical_palette (ColorPalette)
  • size_range_min (Float64)
  • size_range_max (Float64)
  • show_legend (Bool)
  • scale (Float64)
  • raster_supersample (Int)
  • color_by_sign (Bool)
  • mark_color_negative (Color)
  • bullet_range_color_light (Color)
  • bullet_range_color_dark (Color)
  • waterfall_total_color (Color)
  • radialbar_track_color (Color)
  • treemap_label_color (Color)
  • radar_fill_alpha (UInt8)
  • sankey_flow_alpha (UInt8)
  • shape_by_category (Bool)
  • fill_pattern_by_category (Bool)
  • line_smoothing (Float64)
  • title_font_size (Float64)
  • subtitle_font_size (Float64)
  • subtitle_color (Color)
  • axis_title_font_size (Float64)
  • annotation_color (Color)
  • annotation_area_color (Color)
  • histogram_edge_color (Color)
  • show_axis_left (Bool)
  • show_axis_right (Bool)
  • show_axis_top (Bool)
  • show_axis_bottom (Bool)
  • x_axis_position (AxisPosition)
  • y_axis_position (AxisPosition)
  • font_family (String)
  • title_bold (Bool)
  • halo_alpha (UInt8)
  • tick_length (Int)
  • label_gap (Int)
  • legend_width (Int)
  • legend_swatch_size (Int)
  • legend_row_gap (Int)
  • continuous_legend_bar_width (Int)
  • continuous_legend_bar_height (Int)
  • margin_buffer (Int)
  • error_bar_cap_width (Float64)
  • output_format (OutputFormat)
  • tooltips (Tooltips)
  • missing (Missing)
  • missing_category_label (String)
  • auto_tooltip_limit (Int)
  • show_data_labels (Bool)
  • gridline_style (LineStyle)
  • annotation_arrow_width (Float64)
  • annotation_line_style (LineStyle)
  • legend_position (LegendPosition)
  • x_label_rotation (XAxisLabelRotation)
  • x_tick_format (TickFormat)
  • y_tick_format (TickFormat)
  • self (Self)

Returns:

Self

default 

@staticmethod
fn def default() -> Self

Theme() under a name that reads clearly at call sites like .theme(Theme.default()).

Returns:

Self