plottable package#

Submodules#

plottable.cell module#

plottable.cell.create_cell(column_type: plottable.column_def.ColumnType, *args, **kwargs) → plottable.cell.TableCell#

Factory Function to create a specific TableCell depending on column_type.

Parameters

column_type (ColumnType) – plottable.column_def.ColumnType

Returns

plottable.cell.TableCell

Return type

TableCell

class plottable.cell.Cell(xy: Tuple[float, float], width: float = 1, height: float = 1)#

Bases: object

A cell is a rectangle defined by the lower left corner xy and it’s width and height.

property x: float#
property y: float#
class plottable.cell.TableCell(xy: Tuple[float, float], content: Any, row_idx: int, col_idx: int, width: float = 1, height: float = 1, ax: Optional[matplotlib.axes._axes.Axes] = None, rect_kw: Dict[str, Any] = {})#

Bases: plottable.cell.Cell

A TableCell class for a plottable.table.Table.

draw()#
class plottable.cell.SubplotCell(xy: Tuple[float, float], content: Any, row_idx: int, col_idx: int, plot_fn: Callable, plot_kw: Dict[str, Any] = {}, width: float = 1, height: float = 1, ax: Optional[matplotlib.axes._axes.Axes] = None, rect_kw: Dict[str, Any] = {})#

Bases: plottable.cell.TableCell

A SubplotTableCell class for a plottable.table.Table that creates a subplot on top of it’s rectangle patch.

plot()#
make_axes_inset()#
draw()#
class plottable.cell.TextCell(xy: Tuple[float, float], content: str | numbers.Number, row_idx: int, col_idx: int, width: float = 1, height: float = 1, ax: Optional[matplotlib.axes._axes.Axes] = None, rect_kw: Dict[str, Any] = {}, textprops: Dict[str, Any] = {}, padding: float = 0.1)#

Bases: plottable.cell.TableCell

A TextCell class for a plottable.table.Table that creates a text inside it’s rectangle patch.

draw()#
set_text()#
class plottable.cell.Sequence(cells: List[plottable.cell.TableCell], index: int)#

Bases: object

A Sequence of Table Cells.

append(cell: plottable.cell.TableCell)#

Appends another TableCell to its cells propery.

Parameters

cell (TableCell) – A TableCell object

set_alpha(*args) → plottable.cell.Sequence#

Sets the alpha for all cells of the Sequence and returns self.

Returns

A Sequence of Cells

Return type

self[Sequence]

set_color(*args) → plottable.cell.Sequence#

Sets the color for all cells of the Sequence and returns self.

Returns

A Sequence of Cells

Return type

self[Sequence]

set_facecolor(*args) → plottable.cell.Sequence#

Sets the facecolor for all cells of the Sequence and returns self.

Returns

A Sequence of Cells

Return type

self[Sequence]

set_edgecolor(*args) → plottable.cell.Sequence#

Sets the edgecolor for all cells of the Sequence and returns self.

Returns

A Sequence of Cells

Return type

self[Sequence]

set_fill(*args) → plottable.cell.Sequence#

Sets the fill for all cells of the Sequence and returns self.

Returns

A Sequence of Cells

Return type

self[Sequence]

set_hatch(*args) → plottable.cell.Sequence#

Sets the hatch for all cells of the Sequence and returns self.

Returns

A Sequence of Cells

Return type

self[Sequence]

set_linestyle(*args) → plottable.cell.Sequence#

Sets the linestyle for all cells of the Sequence and returns self.

Returns

A Sequence of Cells

Return type

self[Sequence]

set_linewidth(*args) → plottable.cell.Sequence#

Sets the linewidth for all cells of the Sequence and returns self.

Returns

A Sequence of Cells

Return type

self[Sequence]

set_fontcolor(*args) → plottable.cell.Sequence#

Sets the fontcolor for all cells texts of the Sequence and returns self.

Returns

A Sequence of Cells

Return type

self[Sequence]

set_fontfamily(*args) → plottable.cell.Sequence#

Sets the fontfamily for all cells texts of the Sequence and returns self.

Returns

A Sequence of Cells

Return type

self[Sequence]

set_fontsize(*args) → plottable.cell.Sequence#

Sets the fontsize for all cells texts of the Sequence and returns self.

Returns

A Sequence of Cells

Return type

self[Sequence]

set_ha(*args) → plottable.cell.Sequence#

Sets the horizontal alignment for all cells texts of the Sequence and returns self.

Returns

A Sequence of Cells

Return type

self[Sequence]

set_ma(*args) → plottable.cell.Sequence#

Sets the multialignment for all cells tests of the Sequence and returns self.

Returns

A Sequence of Cells

Return type

self[Sequence]

class plottable.cell.Row(cells: List[plottable.cell.TableCell], index: int)#

Bases: plottable.cell.Sequence

A Row of TableCells.

get_xrange() → Tuple[float, float]#

Gets the xrange of the Row.

Returns

Tuple of min and max x.

Return type

Tuple[float, float]

get_yrange() → Tuple[float, float]#

Gets the yrange of the Row.

Returns

Tuple of min and max y.

Return type

Tuple[float, float]

property x: float#
property y: float#
property height: float#
class plottable.cell.Column(cells: List[plottable.cell.TableCell], index: int, name: Optional[str] = None)#

Bases: plottable.cell.Sequence

A Column of TableCells.

get_xrange() → Tuple[float, float]#

Gets the xrange of the Column.

Returns

Tuple of min and max x.

Return type

Tuple[float, float]

get_yrange() → Tuple[float, float]#

Gets the yrange of the Column.

Returns

Tuple of min and max y.

Return type

Tuple[float, float]

property x: float#
property y: float#
property width: float#

plottable.cmap module#

plottable.cmap.normed_cmap(s: pandas.core.series.Series, cmap: matplotlib.colors.LinearSegmentedColormap, num_stds: float = 2.5) → Callable#

Returns a normalized colormap function that takes a float as an argument and returns an rgba value.

Parameters

  • s (pd.Series) – a series of numeric values

  • cmap (matplotlib.colors.LinearSegmentedColormap) – matplotlib Colormap

  • num_stds (float, optional) – vmin and vmax are set to the median ± num_stds. Defaults to 2.5.

Returns

Callable that takes a float as an argument and returns an rgba value.

Return type

Callable

plottable.cmap.centered_cmap(s: pandas.core.series.Series, cmap: matplotlib.colors.LinearSegmentedColormap, num_stds: float = 2.5, center: float | None = 0) → Callable#

Returns a centered and normalized colormap function that takes a float as an argument and returns an rgba value.

Parameters

  • s (pd.Series) – a series of numeric values

  • cmap (matplotlib.colors.LinearSegmentedColormap) – matplotlib Colormap

  • num_stds (float, optional) – vmin and vmax are set to the median ± num_stds. Defaults to 2.5.

Returns

Callable that takes a float as an argument and returns an rgba value.

Return type

Callable

plottable.column_def module#

class plottable.column_def.ColumnType(value)#

Bases: enum.Enum

The Column Type.

Column Types are:

STRING = “string” SUBPLOT = “subplot”

STRING = 'string'#
SUBPLOT = 'subplot'#
class plottable.column_def.ColumnDefinition(name: str, title: typing.Optional[str] = None, width: float = 1, textprops: typing.Dict[str, typing.Any] = <factory>, formatter: typing.Optional[typing.Union[typing.Callable, str]] = None, cmap: typing.Optional[typing.Union[typing.Callable, matplotlib.colors.LinearSegmentedColormap]] = None, text_cmap: typing.Optional[typing.Union[typing.Callable, matplotlib.colors.LinearSegmentedColormap]] = None, group: typing.Optional[str] = None, plot_fn: typing.Optional[typing.Callable] = None, plot_kw: typing.Dict[str, typing.Any] = <factory>, border: typing.Optional[typing.Union[str, typing.List]] = None)#

Bases: object

A Class defining attributes for a table column.

Parameters

  • name – str: the column name

  • title – str = None: the plotted title to override the column name

  • width – float = 1: the width of the column as a factor of the default width

  • textprops – Dict[str, Any] = field(default_factory=dict) textprops provided to each textcell

  • formatter – Callable | str = None: Either A Callable or a builtin format string to format the appearance of the texts

  • cmap – Callable | LinearSegmentedColormap = None: A Callable that returns a color based on the cells value.

  • text_cmap – Callable | LinearSegmentedColormap = None: A Callable that returns a color based on the cells value.

  • group – str = None: Each group will get a spanner column label above the column labels.

  • plot_fn – Callable = None A Callable that will take the cells value as input and create a subplot on top of each cell and plot onto them. To pass additional arguments to it, use plot_kw (see below).

  • plot_kw – Dict[str, Any] = field(default_factory=dict) Additional keywords provided to plot_fn.

  • border – str | List = None: Plots a vertical borderline. can be either “left” / “l”, “right” / “r” or “both”

Formatting digits reference:

source: https://www.pythoncheatsheet.org/cheatsheet/string-formatting

number format output description —— —— —— ———– 3.1415926 {:.2f} 3.14 Format float 2 decimal places 3.1415926 {:+.2f} +3.14 Format float 2 decimal places with sign -1 {:+.2f} -1.00 Format float 2 decimal places with sign 2.71828 {:.0f} 3 Format float with no decimal places 4 {:0>2d} 04 Pad number with zeros (left padding, width 2) 4 {:x<4d} 4xxx Pad number with x’s (right padding, width 4) 10 {:x<4d} 10xx Pad number with x’s (right padding, width 4) 1000000 {:,} 1,000,000 Number format with comma separator 0.35 {:.2%} 35.00% Format percentage 1000000000 {:.2e} 1.00e+09 Exponent notation 11 {:11d} 11 Right-aligned (default, width 10) 11 {:<11d} 11 Left-aligned (width 10) 11 {:^11d} 11 Center aligned (width 10)

name: str#
title: str = None#
width: float = 1#
textprops: Dict[str, Any]#
formatter: Union[Callable, str] = None#
cmap: Union[Callable, matplotlib.colors.LinearSegmentedColormap] = None#
text_cmap: Union[Callable, matplotlib.colors.LinearSegmentedColormap] = None#
group: str = None#
plot_fn: Callable = None#
plot_kw: Dict[str, Any]#
border: Union[str, List] = None#
plottable.column_def.ColDef#

alias of plottable.column_def.ColumnDefinition

plottable.font module#

plottable.font.contrasting_font_color(rgb: Tuple[float], light_color: str = '#ffffff', dark_color: str = '#000000', thresh=186) → str#

Automatically chooses a light (“#ffffff”) or dark (“#000000”) fontcolor based on a (background) color.

Parameters

  • rgb (Tuple[float]) – rgb color tuple

  • light_color (str, optional) – the light color to use for dark backgrounds. Defaults to #ffffff

  • dark_color (str, optional) – the dark color to use for light backgrounds. Defaults to #000000

  • thresh (int, optional) – threshold to use. Defaults to 186.

Returns

color hex code

Return type

str

plottable.font.contrasting_font_color_w3c(rgb: Tuple[float], light_color: str = '#ffffff', dark_color: str = '#000000', adjust: float = - 0.05) → str#

Automatically chooses a light (“#ffffff”) or dark (“#000000”) fontcolor based on a (background) color.

Parameters

  • rgb (Tuple[float]) – rgb color tuple

  • light_color (str, optional) – the light color to use for dark backgrounds. Defaults to #ffffff

  • dark_color (str, optional) – the dark color to use for light backgrounds. Defaults to #000000

  • adjust (float, optional) – threshold to use. Defaults to -0.05.

Returns

color hex code

Return type

str

plottable.font.contrasting_font_color_(rgb: Tuple[float], light_color: str = '#ffffff', dark_color: str = '#000000') → str#

Automatically chooses a light (“#ffffff”) or dark (“#000000”) fontcolor based on a (background) color.

Parameters

  • rgb (Tuple[float]) – rgb color tuple

  • light_color (str, optional) – the light color to use for dark backgrounds. Defaults to #ffffff

  • dark_color (str, optional) – the dark color to use for light backgrounds. Defaults to #000000

Returns

color hex code

Return type

str

plottable.formatters module#

plottable.formatters.apply_string_formatter(fmt: str, val: str | numbers.Number) → str#
plottable.formatters.apply_formatter(formatter: Union[str, Callable], content: str | numbers.Number) → str#

Applies a formatter to the content.

Parameters

  • formatter (str | Callable) – the string formatter. Can either be a string format, ie “{:2f}” for 2 decimal places. Or a Callable that is applied to the content.

  • content (str | Number) – The content to format

Raises

TypeError – when formatter is not of type str or Callable.

Returns

a formatted string

Return type

str

plottable.formatters.decimal_to_percent(val: float) → str#
Formats Numbers to a string, replacing

0 with “–” 1 with “✓” values < 0.01 with “<1%” and values > 0.99 with “>99%”

Parameters

val (float) – numeric value to format

Returns

formatted numeric value as string

Return type

str

plottable.formatters.tickcross(val: numbers.Number | bool) → str#

formats a bool or (0, 1) value to a tick “✔” or cross “✖”.

Parameters

val (Number | bool) – bool or (0, 1) value to format

Returns

formatted value as string

Return type

str

plottable.formatters.signed_integer(val: int) → str#

formats an integer to a string that includes the sign, ie. 1 to “+1”.

Parameters

val (int) – integer value to format

Returns

formatted value as string

Return type

str

plottable.helpers module#

plottable.plots module#

plottable.plots.image(ax: matplotlib.axes._axes.Axes, path: str) → matplotlib.image.AxesImage#

Plots an image on the axes.

Parameters

  • ax (matplotlib.axes.Axes) – Axes

  • path (str) – path to image file

Returns

matplotlib.image.AxesImage

plottable.plots.monochrome_image(ax: matplotlib.axes._axes.Axes, path: str) → matplotlib.image.AxesImage#

Plots a monochrome image on the axes.

Parameters

  • ax (matplotlib.axes.Axes) – Axes

  • path (str) – path to image file

Returns

matplotlib.image.AxesImage

plottable.plots.circled_image(ax: matplotlib.axes._axes.Axes, path: str, **circle_kwargs) → matplotlib.image.AxesImage#

Plots an image cropped to a circle on the axes. The cropping radius is the minimum of (width, height) of the image.

Parameters

  • ax (matplotlib.axes.Axes) – Axes

  • path (str) – path to image file

Returns

matplotlib.image.AxesImage

plottable.plots.bar(ax: matplotlib.axes._axes.Axes, val: float, xlim: Tuple[float, float] = (0, 1), cmap: Optional[matplotlib.colors.Colormap] = None, plot_bg_bar: bool = False, annotate: bool = False, textprops: Dict[str, Any] = {}, formatter: Optional[Callable] = None, **kwargs) → matplotlib.container.BarContainer#

Plots a bar on the axes.

Parameters

  • ax (matplotlib.axes.Axes) – Axes

  • val (float) – value

  • xlim (Tuple[float, float], optional) – data limit for the x-axis. Defaults to (0, 1).

  • cmap (matplotlib.colors.Colormap, optional) – colormap. Defaults to None.

  • plot_bg_bar (bool, optional) – whether to plot a background bar. Defaults to False.

  • annotate (bool, optional) – whether to annotate the value. Defaults to False.

  • textprops (Dict[str, Any], optional) – textprops passed to ax.text. Defaults to {}.

  • formatter (Callable, optional) – a string formatter. Can either be a string format, ie “{:2f}” for 2 decimal places. Or a Callable that is applied to the value. Defaults to None.

Returns

matplotlib.container.BarContainer

plottable.plots.percentile_bars(ax: matplotlib.axes._axes.Axes, val: float, color: Optional[str] = None, background_color: Optional[str] = None, cmap: Optional[matplotlib.colors.Colormap] = None, is_pct=False, rect_kw: Dict[str, Any] = {}) → List[matplotlib.patches.FancyBboxPatch]#

Plots percentile bars on the axes.

Parameters

  • ax (matplotlib.axes.Axes) – Axes

  • val (float) – value

  • color (str, optional) – color of the bars. Defaults to None.

  • background_color (str, optional) – background_color of the bars if value is not reached. Defaults to None.

  • cmap (matplotlib.colors.Colormap, optional) – Colormap. Defaults to None.

  • is_pct (bool, optional) – whether the value is given not as a decimal, but as a value between 0 and 100. Defaults to False.

  • rect_kw (Dict[str, Any], optional) – rect keywords passed to matplotlib.patches.FancyBboxPatch. Defaults to {}.

Returns

List[matplotlib.patches.FancyBboxPatch]

plottable.plots.percentile_stars(ax: matplotlib.axes._axes.Axes, val: float, n_stars: int = 5, color: str = 'orange', background_color: Optional[str] = None, is_pct: bool = False, padding: float = 0.1, **kwargs) → matplotlib.collections.PathCollection#

Plots x out of 5 percentile stars on the axes.

Parameters

  • ax (matplotlib.axes.Axes) – Axes

  • val (float) – value

  • n_stars (int, optional) – number of maximum stars. Defaults to 5.

  • color (str, optional) – color of the stars. Defaults to “orange”.

  • background_color (str, optional) – background_color of the stars if value is not reached. Defaults to None.

  • is_pct (bool, optional) – whether the value is given not as a decimal, but as a value between 0 and 100. Defaults to False.

  • padding (float, optional) – horizontal and vertical padding from stars to axes border. Defaults to 0.1.

Returns

matplotlib.collections.PathCollection

plottable.plots.progress_donut(ax: matplotlib.axes._axes.Axes, val: float, radius: float = 0.45, color: Optional[str] = None, background_color: Optional[str] = None, width: float = 0.05, is_pct: bool = False, textprops: Dict[str, Any] = {}, formatter: Optional[Callable] = None, **kwargs) → List[matplotlib.patches.Wedge]#

Plots a Progress Donut on the axes.

Parameters

  • ax (matplotlib.axes.Axes) – Axes

  • val (float) – value

  • radius (float, optional) – radius of the progress donut. Defaults to 0.45.

  • color (str, optional) – color of the progress donut. Defaults to None.

  • background_color (str, optional) – background_color of the progress donut where the value is not reached. Defaults to None.

  • width (float, optional) – width of the donut wedge. Defaults to 0.05.

  • is_pct (bool, optional) – whether the value is given not as a decimal, but as a value between 0 and 100. Defaults to False.

  • textprops (Dict[str, Any], optional) – textprops passed to ax.text. Defaults to {}.

  • formatter (Callable, optional) – a string formatter. Can either be a string format, ie “{:2f}” for 2 decimal places. Or a Callable that is applied to the value. Defaults to None.

Returns

List[matplotlib.patches.Wedge]

plottable.table module#

Module containing Table Class to plot matplotlib tables.

class plottable.table.Table(df: pandas.core.frame.DataFrame, ax: Optional[matplotlib.axes._axes.Axes] = None, index_col: Optional[str] = None, columns: Optional[List[str]] = None, column_definitions: Optional[List[plottable.column_def.ColumnDefinition]] = None, textprops: Dict[str, Any] = {}, cell_kw: Dict[str, Any] = {}, col_label_cell_kw: Dict[str, Any] = {}, col_label_divider: bool = True, footer_divider: bool = False, row_dividers: bool = True, row_divider_kw: Dict[str, Any] = {}, col_label_divider_kw: Dict[str, Any] = {}, footer_divider_kw: Dict[str, Any] = {}, column_border_kw: Dict[str, Any] = {}, even_row_color: Optional[Union[str, Tuple]] = None, odd_row_color: Optional[Union[str, Tuple]] = None)#

Bases: object

Class to plot a beautiful matplotlib table.

Parameters

  • df (pd.DataFrame) – A pandas DataFrame with your table data

  • ax (mpl.axes.Axes, optional) – matplotlib axes. Defaults to None.

  • index_col (str, optional) – column to set as the DataFrame index. Defaults to None.

  • columns (List[str], optional) – columns to use. If None defaults to all columns.

  • column_definitions (List[plottable.column_def.ColumnDefinition], optional) – ColumnDefinitions for columns that should be styled. Defaults to None.

  • textprops (Dict[str, Any], optional) – textprops are passed to each TextCells matplotlib.pyplot.text. Defaults to {}.

  • cell_kw (Dict[str, Any], optional) – cell_kw are passed to to each cells matplotlib.patches.Rectangle patch. Defaults to {}.

  • col_label_cell_kw (Dict[str, Any], optional) – col_label_cell_kw are passed to to each ColumnLabels cells matplotlib.patches.Rectangle patch. Defaults to {}.

  • col_label_divider (bool, optional) – Whether to plot a divider line below the column labels. Defaults to True.

  • col_label_divider_kw (Dict[str, Any], optional) – col_label_divider_kw are passed to plt.plot. Defaults to {}.

  • footer_divider (bool, optional) – Whether to plot a divider line below the table. Defaults to False.

  • footer_divider_kw (Dict[str, Any], optional) – footer_divider_kw are passed to plt.plot. Defaults to {}.

  • row_dividers (bool, optional) – Whether to plot divider lines between rows. Defaults to True.

  • row_divider_kw (Dict[str, Any], optional) – row_divider_kw are passed to plt.plot. Defaults to {}.

  • column_border_kw (Dict[str, Any], optional) – column_border_kw are passed to plt.plot. Defaults to {}.

  • even_row_color (str | Tuple, optional) – facecolor of the even row cell’s patches. Top Row has an even (0) index.

  • odd_row_color (str | Tuple, optional) – facecolor of the even row cell’s patches. Top Row has an even (0) index.

Examples

>>> import matplotlib.pyplot as plt
>>> import numpy as np
>>> import pandas as pd
>>>
>>> from plottable import Table
>>>
>>> d = pd.DataFrame(np.random.random((10, 5)), columns=["A", "B", "C", "D", "E"]).round(2)
>>> fig, ax = plt.subplots(figsize=(5, 8))
>>> tab = Table(d)
>>>
>>> plt.show()
get_column(name: str) → plottable.cell.Column#

Gets a Column by its column_name.

Parameters

name (str) – the column_name in the df.

Returns

A Column of the Table

Return type

Column

get_column_by_index(index: int) → plottable.cell.Column#

Gets a Column by its numeric index.

Parameters

index (int) – numeric index

Returns

A Column of the Table

Return type

Column

get_even_rows() → List[plottable.cell.Row]#
get_odd_rows() → List[plottable.cell.Row]#
set_alternating_row_colors(color: Optional[Union[str, Tuple[float]]] = None, color2: Optional[Union[str, Tuple[float]]] = None) → plottable.table.Table#

Sets the color of even row’s rectangle patches to color.

Parameters

  • color (str) – color recognized by matplotlib for the even rows 0 …

  • color2 (str) – color recognized by matplotlib for the odd rows 1 …

Returns

plottable.table.Table

Return type

Table

autoset_fontcolors(fn: Optional[Callable] = None, colnames: Optional[List[str]] = None, **kwargs) → plottable.table.Table#

Sets the fontcolor of each table cell based on the facecolor of its rectangle patch.

Parameters

  • fn (Callable, optional) – Callable that takes the rectangle patches facecolor as rgba-value as argument. Defaults to plottable.font.contrasting_font_color if fn is None.

  • colnames (List[str], optional) – columns to apply the function to

  • fn. (kwargs are passed to) –

Returns

plottable.table.Table

Module contents#