simplebench.reporters.graph.matplotlib package

Matplotlib graph reporter module.

This module provides common base functionality for Matplotlib-based graph reporters. The MatPlotLibOptions and MatPlotLibReporter classes are not intended to be used directly, but rather to be subclassed by specific reporters for line plots, bar charts, scatter plots, etc.

Public API

• MatPlotLibOptions: Options specific to Matplotlib based graph reporters.

• MatPlotLibReporter: Base class for Matplotlib based graph reporters.

• Style: Enumeration of available styles.

• Theme: Theme management for Matplotlib based graph reporters.

• SUPPORTED_IMAGE_TYPES: Frozen set of supported image output types.

class simplebench.reporters.graph.matplotlib.MatPlotLibOptions(

width: int | None = None,

height: int | None = None,

dpi: int | None = None,

y_starts_at_zero: bool | None = None,

x_labels_rotation: float | None = None,

style: Style | None = None,

theme: Theme | None = None,

image_type: ImageType | None = None,

)

Bases: GraphOptions

Class for holding MatPlotLib graph reporter specific options.

This class extends the GraphOptions interface and forms a new interface for options specific to MatPlotLib-based graph reporters.

It makes it easy to create graph reporters with MatPlotLib by providing a standard set of options that can be used across multiple reporters via subclassing.

It includes the defaults for various MatPlotLib reporter defaults that can be set globally for all MatPlotLib reporters via static methods, as well as instance-specific options that can be set when creating a MatPlotLibOptions instance or when creating a benchmark test case.

The philosophy behind having both static/global defaults and instance-specific options is to provide flexibility in configuration in a ‘simple things should be simple, complex things should be possible’ manner.

Users can set global defaults that apply to all MatPlotLib reporters, ensuring easy consistency across reports. At the same time, instance-specific options allow for customization on a per-report basis, enabling users to tailor the behavior of individual reports as needed.

The baseline defaults provided here are intended to offer a good balance between quality, appearance, and performance for most common use cases.

Those defaults are as follows:

• Width: 1500 pixels

• Height: 750 pixels

• DPI: 150

• Y-axis starts at zero: True

• X-axis labels rotation: 45.0 degrees

• Style: DARK_BACKGROUND

• Theme: DefaultTheme

• ImageType: SVG

These defaults are used both by Case instances when creating reports for specific test cases and by Choice instances when creating reports for all test cases under that Choice.

The semantics are that options take precedence over options take precedence over the class defaults. This allows for flexible configuration at multiple levels.

Variables:

• width (int) – The default width of the MatPlotLib output in pixels when rendered.

• height (int) – The default height of the MatPlotLib output in pixels when rendered.

• dpi (int) – The default DPI (dots per inch) for the MatPlotLib output when rendered.

• y_starts_at_zero (bool) – The default for whether the Y-axis for graphs should start at zero.

• x_labels_rotation (float) – The default rotation angle in degrees for X-axis labels.

• style (Style) – The default style for the MatPlotLib graphs.

• theme (Theme) – The default theme to use for the MatPlotLib graphs.

• image_type (ImageType) – The output image format for the graph files.

Create a MatPlotLibOptions instance.

To ensure accuracy in graph rendering, the default width, height, and DPI should be set with the width and height being exact multiples of the DPI. This is because the underlying rendering engine uses DPI to determine the pixel dimensions of the output graph from the specified width and height in inches.

If the width and height are not exact multiples of the DPI, it may lead to unexpected scaling or distortion of the graph when rendered, as the rendering engine may round the pixel dimensions to the nearest whole number.

The default values provided here are chosen to balance quality and performance for most common use cases. However, users can customize these values based on their specific requirements for graph resolution and size.

The use of None for (or, equivalently the omission of) any argument indicates that the default value defined in the next lower precedence level should be used.

Parameters:

• width (int | None) – The width in pixels of a MatPlotLib output when rendered. It should be an exact multiple of the dpi and can only be between 500 and 4000 pixels. If None, the default MatPlotLibOptions default width will be used.

• height (int | None) – The height in pixels of a MatPlotLib output when rendered. It should be an exact multiple of the dpi and can only be between 500 and 4000 pixels. If None, the default MatPlotLibOptions default height will be used.

• dpi (int | None) – The default DPI (dots per inch) for a MatPlotLib output. It must be between 50 and 400.

• y_starts_at_zero (bool | None) – Whether the Y-axis should start at zero.

• x_labels_rotation (float | None) – The rotation angle in degrees for X-axis labels.

• style (Style | None) – The default style for the MatPlotLib graphs.

• theme (Theme | None) – The theme to use for the MatPlotLib graphs.

• image_type (ImageType | None) – The output format for the graph files.

Raises:

• SimpleBenchTypeError – If any of the arguments are of incorrect type.

• SimpleBenchValueError – If any of the arguments have invalid values.

DEFAULT_KWARGS: ClassVar[dict[str, object]] = {'dpi': 150, 'height': 750, 'image_type': ImageType.SVG, 'style': Style.DARK_BACKGROUND, 'theme': {'axes.grid': True, 'axes.labelsize': 16.0, 'axes.titlesize': 20.0, 'figure.dpi': 150.0, 'grid.color': '#444444', 'grid.linestyle': '-', 'legend.fontsize': 14.0, 'legend.framealpha': 1.0, 'legend.shadow': True, 'legend.title_fontsize': 16.0, 'xtick.labelsize': 12.0, 'ytick.labelsize': 12.0}, 'width': 1500, 'x_labels_rotation': 45.0, 'y_starts_at_zero': True}

Default keyword arguments for MatPlotLibOptions constructor.

• width: int = 1500

• height: int = 750

• dpi: int = 150

• y_starts_at_zero: bool = True

• x_labels_rotation: float = 45.0

• style: Style = DARK_BACKGROUND

• theme: Theme = DefaultTheme

• image_type: ImageType = SVG

property dpi: int

Return the Dots Per Inch (DPI) of the graph when rendered.

Returns:

The default DPI of the graph when rendered.

Return type:

int

classmethod get_default_dpi() → int

Return the default DPI for all MatPlotLib graphs.

If no default DPI has been explicitly set, returns the hardcoded default DPI of 150.

Returns:

The default DPI for all MatPlotLib graphs.

Return type:

int

classmethod get_default_height() → int

Return the default height in pixels for all MatPlotLib graphs.

If no default height has been explicitly set, returns the hardcoded default height of 750.

Returns:

The default height in pixels for all MatPlotLib graphs.

Return type:

int

static get_default_image_type() → ImageType

Return the default image type for all MatPlotLib graphs.

If no default image type has been explicitly set, returns SVG.

Returns:

The default image type for all MatPlotLib graphs.

Return type:

ImageType

classmethod get_default_style() → Style

Return the default style for MatPlotLib graphs.

If no default style has been explictly set, returns the hardcoded built-in DARK_BACKGROUND.

Returns:

The default style for MatPlotLib graphs.

Return type:

Style

classmethod get_default_theme() → Theme

Return the default theme for MatPlotLib graphs.

If no default theme has been explictly set, returns Default.

Returns:

The default theme for MatPlotLib graphs.

Return type:

Theme

classmethod get_default_width() → int

Return the default width in pixels for all MatPlotLib graphs.

If no default width has been explicitly set, then it returns the hardcoded default width of 1500.

Returns:

The default width in pixels for all MatPlotLib graphs.

Return type:

int

classmethod get_default_x_labels_rotation() → float

Return the default rotation angle in degrees for X-axis labels for all MatPlotLib graphs.

If no default has been explicitly set, returns the hardcoded built-in default of 45.0 degrees.

Returns:

The default rotation angle in degrees for X-axis labels for all MatPlotLib graphs.

Return type:

float

classmethod get_default_y_starts_at_zero() → bool

Return the default value for whether Y-axis starts at zero for all MatPlotLib graphs.

If no default has been explicitly set, returns the hardcoded built-in default of True.

Returns:

The default value for whether Y-axis starts at zero for all MatPlotLib graphs.

Return type:

bool

classmethod get_hardcoded_default_dpi() → int

Return the hardcoded default DPI for all MatPlotLib graphs.

Returns:

The hardcoded default DPI for all MatPlotLib graphs.

Return type:

int

classmethod get_hardcoded_default_height() → int

Return the hardcoded default height in pixels for all MatPlotLib graphs.

Returns:

The hardcoded default height in pixels for all MatPlotLib graphs.

Return type:

int

classmethod get_hardcoded_default_image_type() → ImageType

Return the hardcoded default image type for all MatPlotLib graphs.

Returns:

The hardcoded default image type for all MatPlotLib graphs.

Return type:

ImageType

classmethod get_hardcoded_default_style() → Style

Return the hardcoded default style for all MatPlotLib graphs.

Returns:

The hardcoded default style for all MatPlotLib graphs.

Return type:

Style

classmethod get_hardcoded_default_theme() → Theme

Return the hardcoded default theme for all MatPlotLib graphs.

Returns:

The hardcoded default theme for all MatPlotLib graphs.

Return type:

Theme

classmethod get_hardcoded_default_width() → int

Return the hardcoded default width in pixels for all MatPlotLib graphs.

Returns:

The hardcoded default width in pixels for all MatPlotLib graphs.

Return type:

int

classmethod get_hardcoded_default_x_labels_rotation() → float

Return the hardcoded default rotation angle in degrees for X-axis labels for all MatPlotLib graphs.

Returns:

The hardcoded default rotation angle in degrees for X-axis labels for all MatPlotLib graphs.

Return type:

float

classmethod get_hardcoded_default_y_starts_at_zero() → bool

Return the hardcoded default value for whether Y-axis starts at zero for all MatPlotLib graphs.

Returns:

The hardcoded default value for whether Y-axis starts at zero for all MatPlotLib graphs.

Return type:

bool

property height: int

Return the height in pixels of the graph when rendered.

Returns:

The height of the graph in pixels when rendered.

Return type:

int

property image_type: ImageType

Return the output format for the graph files.

Returns:

The output image format for the graph files.

Return type:

ImageType

classmethod set_default_dpi(

dpi: int | None,

) → None

Set the default DPI for all MatPlotLib graphs.

If dpi is set to None, the built-in hardcoded default DPI will be restored.

Parameters:

dpi (int | None) – The DPI to set as the default for MatPlotLib graphs. If None, the built-in default DPI will be used. The DPI must be between 50 and 400.

Raises:

• SimpleBenchTypeError – If the dpi is not an integer or None.

• SimpleBenchValueError – If the dpi is not within the valid range.

classmethod set_default_height(

height: int | None,

) → None

Set the default height in pixels for all MatPlotLib graphs.

If height is set to None, the built-in hardcoded default height will be restored.

Parameters:

height (int | None) – The height to set as the default for MatPlotLib graphs. If None, the built-in default height will be used. The height must be between 500 and 4000 pixels.

Raises:

• SimpleBenchTypeError – If the height is not an integer or None.

• SimpleBenchValueError – If the height is not within the valid range.

static set_default_image_type(

image_type: ImageType | None,

) → None

Set the default image type for all MatPlotLib graphs.

If image_type is set to None, the built-in default image type will be restored.

Parameters:

image_type (ImageType | None) – The image type to set as the default for MatPlotLib graphs. If None, the built-in default image type will be used.

Raises:

SimpleBenchTypeError – If the image_type is not an ImageType enum member or None.

classmethod set_default_style(

style: Style | None = None,

) → None

Set the default style/theme for all MatPlotLib graphs.

This static method allows setting a global default style for all MatPlotLib graphs. If set to None, the build-in hardcoded default MatPlotLib style will be used.

Parameters:

style (Style | None) – The style to set as the default for MatPlotLib graphs.

Raises:

SimpleBenchTypeError – If the style is not a Style enum member or None.

classmethod set_default_theme(

theme: Theme | None = None,

) → None

Set the default theme for all MatPlotLib graphs.

This static method allows setting a global default theme for all MatPlotLib graphs. If set to None, the built-in hardcoded default MatPlotLib theme (DefaultTheme) will be used.

Parameters:

theme (Theme | None) – The theme to set as the default for MatPlotLib graphs.

Raises:

SimpleBenchTypeError – If the theme is not a Theme instance or None.

classmethod set_default_width(

width: int | None,

) → None

Set the default width in pixels for all MatPlotLib graphs.

Parameters:

width (int | None) – The width to set as the default for MatPlotLib graphs. If set None, the built-in hardcoded default width will be restored. The width must be between 500 and 4000 pixels.

Raises:

• SimpleBenchTypeError – If the width is not an integer or None.

• SimpleBenchValueError – If the width is not within the valid range.

classmethod set_default_x_labels_rotation(

x_labels_rotation: float | None,

) → None

Set the default rotation angle in degrees for X-axis labels for all MatPlotLib graphs.

Setting this to None will restore the default rotation angle of 45.0 degrees.

Parameters:

x_labels_rotation (float | None) – The rotation angle to set as the default for MatPlotLib graphs.

Raises:

SimpleBenchTypeError – If x_labels_rotation is not a float or None.

classmethod set_default_y_starts_at_zero(

y_starts_at_zero: bool | None,

) → None

Set the default value for whether Y-axis starts at zero for all MatPlotLib graphs

Setting this to None will restore the default hardcoded setting of starting the Y-axis at zero.

Parameters:

y_starts_at_zero (bool | None) – The value to set as the default for MatPlotLib graphs.

Raises:

SimpleBenchTypeError – If y_starts_at_zero is not a bool or None.

property style: Style

Return the style for the MatPlotLib graphs.

Returns:

The style for the MatPlotLib graphs.

Return type:

Style

property theme: Theme

Return the theme to use for the MatPlotLib graphs.

Returns:

The theme to use for the MatPlotLib graphs.

Return type:

Theme

property width: int

Return the width in pixels of the graph when rendered.

Returns:

The width of the graph in pixels when rendered.

Return type:

int

property x_labels_rotation: float

Return the rotation angle in degrees for X-axis labels.

Returns:

The rotation angle in degrees for X-axis labels.

Return type:

float

property y_starts_at_zero: bool

Return whether the Y-axis should start at zero.

Returns:

Whether the Y-axis should start at zero.

Return type:

bool

class simplebench.reporters.graph.matplotlib.MatPlotLibReporter(

config: ReporterConfig,

)

Bases: Reporter

Base class for MatPlotLib based graph reporters in the reporters package.

Initialize the Reporter instance.

Parameters:

config (ReporterConfig) – The configuration object for the reporter.

Raises:

SimpleBenchTypeError – If the provided config is not a ReporterConfig instance.

class simplebench.reporters.graph.matplotlib.Style(value)

Bases: str, Enum

Enumeration of graph styles.

Note

The styles correspond to those available in Matplotlib 3.10.6

BMH = 'bmh'

Bayesian Methods for Hackers style for graphs.

See Bayesian Methods for Hackers

CLASSIC = 'classic'

Light background style for graphs.

Classic matplotlib plotting style

DARK_BACKGROUND = 'dark_background'

Dark background style for graphs.

Set black background default line colors to white.

FIVETHIRTYEIGHT = 'fivethirtyeight'

FiveThirtyEight style for graphs.

Replicated styles from FiveThirtyEight.com

See dataorigami.net

GGPLOT = 'ggplot'

ggplot style for graphs.

Replicates the style of R’s ggplot library.

See everyhue.me

GRAYSCALE = 'grayscale'

Grayscale style for graphs.

Set all colors to grayscale

Note

strings of float values are interpreted by matplotlib as gray values.

PETTROF10 = 'petroff10'

Petroff10 style for graphs.

Color cycle survey palette from Petroff (2021):

See arxiv.org and github.com

SEABORN_V0_8 = 'seaborn-v0_8'

Base Seaborn style for graphs.

SEABORN_V0_8_BRIGHT = 'seaborn-v0_8-bright'

Seaborn bright style for graphs.

SEABORN_V0_8_COLORBLIND = 'seaborn-v0_8-colorblind'

Seaborn colorblind style for graphs.

SEABORN_V0_8_DARK = 'seaborn-v0_8-dark'

Seaborn dark style for graphs.

SEABORN_V0_8_DARKGRID = 'seaborn-v0_8-darkgrid'

Seaborn darkgrid style for graphs.

SEABORN_V0_8_DARK_PALETTE = 'seaborn-v0_8-dark-palette'

Seaborn dark palette style for graphs.

SEABORN_V0_8_DEEP = 'seaborn-v0_8-deep'

Seaborn deep style for graphs.

SEABORN_V0_8_MUTED = 'seaborn-v0_8-muted'

Seaborn muted style for graphs.

SEABORN_V0_8_NOTEBOOK = 'seaborn-v0_8-notebook'

Seaborn notebook style for graphs.

SEABORN_V0_8_PAPER = 'seaborn-v0_8-paper'

Seaborn paper style for graphs.

SEABORN_V0_8_PASTEL = 'seaborn-v0_8-pastel'

Seaborn pastel style for graphs.

SEABORN_V0_8_POSTER = 'seaborn-v0_8-poster'

Seaborn poster style for graphs.

SEABORN_V0_8_TALK = 'seaborn-v0_8-talk'

Seaborn talk style for graphs.

SEABORN_V0_8_TICKS = 'seaborn-v0_8-ticks'

Seaborn ticks style for graphs.

SEABORN_V0_8_WHITE = 'seaborn-v0_8-white'

Seaborn white style for graphs.

SEABORN_V0_8_WHITEGRID = 'seaborn-v0_8-whitegrid'

Seaborn whitegrid style for graphs.

SOLARIZE_LIGHT2 = 'Solarize_Light2'

Solarized light style for graphs.

Solarized color palette taken from ethanschoonover.com

TABLEAU_COLORBLIND10 = 'tableau-colorblind10'

Tableau colorblind10 style for graphs.

class simplebench.reporters.graph.matplotlib.Theme(

rcparams: dict[str, Any] | None = None,

)

Bases: RcParams

An immutable MatPlotLib base theme class for the graphs.

This is a subclass of matplotlib.RcParams that represents a theme for Matplotlib graphs. It can be used to define custom styles for Matplotlib graphs generated by SimpleBench.

See Customizing Matplotlib with style sheets and rcParams for more information on customizing Matplotlib themes.

Initialize a Theme instance.

Parameters:

rcparams (dict[str, Any] | None) – The rcParams to use for the theme. If None, the default Matplotlib rcParams will be used.

replace(

rcparams: dict[str, Any],

) → Theme

Replace some parameters in the theme and return a new Theme instance without modifying the current instance.

new_theme = old_theme.replace({'axes.grid': False, 'figure.dpi': 200})

Parameters:

rcparams (dict[str, Any]) – The new rcParams to use for the theme.

Returns:

A new Theme instance with the updated rcParams.

Return type:

Theme

Subpackages

• simplebench.reporters.graph.matplotlib.enums package
  • Style
    • Style.BMH
    • Style.CLASSIC
    • Style.DARK_BACKGROUND
    • Style.FIVETHIRTYEIGHT
    • Style.GGPLOT
    • Style.GRAYSCALE
    • Style.PETTROF10
    • Style.SEABORN_V0_8
    • Style.SEABORN_V0_8_BRIGHT
    • Style.SEABORN_V0_8_COLORBLIND
    • Style.SEABORN_V0_8_DARK
    • Style.SEABORN_V0_8_DARKGRID
    • Style.SEABORN_V0_8_DARK_PALETTE
    • Style.SEABORN_V0_8_DEEP
    • Style.SEABORN_V0_8_MUTED
    • Style.SEABORN_V0_8_NOTEBOOK
    • Style.SEABORN_V0_8_PAPER
    • Style.SEABORN_V0_8_PASTEL
    • Style.SEABORN_V0_8_POSTER
    • Style.SEABORN_V0_8_TALK
    • Style.SEABORN_V0_8_TICKS
    • Style.SEABORN_V0_8_WHITE
    • Style.SEABORN_V0_8_WHITEGRID
    • Style.SOLARIZE_LIGHT2
    • Style.TABLEAU_COLORBLIND10
  • Submodules
    • simplebench.reporters.graph.matplotlib.enums.style module
      • Style
• simplebench.reporters.graph.matplotlib.reporter package
  • Public API
  • MatPlotLibOptions
    • MatPlotLibOptions.DEFAULT_KWARGS
    • MatPlotLibOptions.dpi
    • MatPlotLibOptions.get_default_dpi()
    • MatPlotLibOptions.get_default_height()
    • MatPlotLibOptions.get_default_image_type()
    • MatPlotLibOptions.get_default_style()
    • MatPlotLibOptions.get_default_theme()
    • MatPlotLibOptions.get_default_width()
    • MatPlotLibOptions.get_default_x_labels_rotation()
    • MatPlotLibOptions.get_default_y_starts_at_zero()
    • MatPlotLibOptions.get_hardcoded_default_dpi()
    • MatPlotLibOptions.get_hardcoded_default_height()
    • MatPlotLibOptions.get_hardcoded_default_image_type()
    • MatPlotLibOptions.get_hardcoded_default_style()
    • MatPlotLibOptions.get_hardcoded_default_theme()
    • MatPlotLibOptions.get_hardcoded_default_width()
    • MatPlotLibOptions.get_hardcoded_default_x_labels_rotation()
    • MatPlotLibOptions.get_hardcoded_default_y_starts_at_zero()
    • MatPlotLibOptions.height
    • MatPlotLibOptions.image_type
    • MatPlotLibOptions.set_default_dpi()
    • MatPlotLibOptions.set_default_height()
    • MatPlotLibOptions.set_default_image_type()
    • MatPlotLibOptions.set_default_style()
    • MatPlotLibOptions.set_default_theme()
    • MatPlotLibOptions.set_default_width()
    • MatPlotLibOptions.set_default_x_labels_rotation()
    • MatPlotLibOptions.set_default_y_starts_at_zero()
    • MatPlotLibOptions.style
    • MatPlotLibOptions.theme
    • MatPlotLibOptions.width
    • MatPlotLibOptions.x_labels_rotation
    • MatPlotLibOptions.y_starts_at_zero
  • MatPlotLibReporter
  • Subpackages
    • simplebench.reporters.graph.matplotlib.reporter.options package
      • MatPlotLibOptions
      • Submodules
  • Submodules
    • simplebench.reporters.graph.matplotlib.reporter.exceptions module
    • simplebench.reporters.graph.matplotlib.reporter.reporter module
      • MatPlotLibReporter
• simplebench.reporters.graph.matplotlib.theme package
  • Theme
    • Theme.replace()
  • Submodules
    • simplebench.reporters.graph.matplotlib.theme.base module
      • Theme
    • simplebench.reporters.graph.matplotlib.theme.default module
      • DefaultTheme
    • simplebench.reporters.graph.matplotlib.theme.exceptions module

Submodules

• simplebench.reporters.graph.matplotlib.constants module
  • SUPPORTED_IMAGE_TYPES