matplotlib.table
#
Tables drawing.
Note
The table implementation in Matplotlib is lightly maintained. For a more featureful table implementation, you may wish to try blume.
Use the factory function table
to create a ready-made
table from texts. If you need more control, use the Table
class and its
methods.
The table consists of a grid of cells, which are indexed by (row, column). The cell (0, 0) is positioned at the top left.
Thanks to John Gill for providing the class and table.
- class matplotlib.table.Cell(xy, width, height, *, edgecolor='k', facecolor='w', fill=True, text='', loc=None, fontproperties=None, visible_edges='closed')[source]#
Bases:
Rectangle
A cell is a
Rectangle
with some associatedText
.As a user, you'll most likely not creates cells yourself. Instead, you should use either the
table
factory function orTable.add_cell
.- Parameters:
- xy2-tuple
The position of the bottom left corner of the cell.
- widthfloat
The cell width.
- heightfloat
The cell height.
- edgecolorcolor
The color of the cell border.
- facecolorcolor
The cell facecolor.
- fillbool
Whether the cell background is filled.
- textstr
The cell text.
- loc{'left', 'center', 'right'}, default: 'right'
The alignment of the text within the cell.
- fontpropertiesdict
A dict defining the font properties of the text. Supported keys and values are the keyword arguments accepted by
FontProperties
.- visible_edgesstr, default: 'closed'
The cell edges to be drawn with a line: a substring of 'BRTL' (bottom, right, top, left), or one of 'open' (no edges drawn), 'closed' (all edges drawn), 'horizontal' (bottom and top), 'vertical' (right and left).
- PAD = 0.1#
Padding between text and rectangle.
- draw(renderer)[source]#
Draw the Artist (and its children) using the given renderer.
This has no effect if the artist is not visible (
Artist.get_visible
returns False).- Parameters:
- renderer
RendererBase
subclass.
- renderer
Notes
This method is overridden in the Artist subclasses.
- get_path()[source]#
Return a
Path
for thevisible_edges
.
- get_text_bounds(renderer)[source]#
Return the text bounds as (x, y, width, height) in table coordinates.
- set(*, agg_filter=<UNSET>, alpha=<UNSET>, angle=<UNSET>, animated=<UNSET>, antialiased=<UNSET>, bounds=<UNSET>, capstyle=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, color=<UNSET>, edgecolor=<UNSET>, facecolor=<UNSET>, fill=<UNSET>, fontsize=<UNSET>, gid=<UNSET>, hatch=<UNSET>, height=<UNSET>, in_layout=<UNSET>, joinstyle=<UNSET>, label=<UNSET>, linestyle=<UNSET>, linewidth=<UNSET>, mouseover=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, text_props=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, width=<UNSET>, x=<UNSET>, xy=<UNSET>, y=<UNSET>, zorder=<UNSET>)[source]#
Set multiple properties at once.
Supported properties are
Property
Description
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
scalar or None
unknown
bool
antialiased
or aabool or None
(left, bottom, width, height)
CapStyle
or {'butt', 'projecting', 'round'}BboxBase
or Nonebool
Patch or (Path, Transform) or None
color
edgecolor
or eccolor or None
facecolor
or fccolor or None
unknown
bool
unknown
str
{'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'}
unknown
bool
JoinStyle
or {'miter', 'round', 'bevel'}object
linestyle
or ls{'-', '--', '-.', ':', '', (offset, on-off-seq), ...}
linewidth
or lwfloat or None
bool
list of
AbstractPathEffect
None or bool or float or callable
bool
(scale: float, length: float, randomness: float)
bool or None
unknown
unknown
str
bool
unknown
unknown
(float, float)
unknown
float
- set_text_props(**kwargs)[source]#
Update the text properties.
Valid keyword arguments are:
Property
Description
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
scalar or None
bool
bool
color
dict with properties for
patches.FancyBboxPatch
unknown
unknown
unknown
color
or ccolor
fontfamily
or family or fontname{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'}
fontproperties
or font or font_propertiesfontsize
or sizefloat or {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}
fontstretch
or stretch{a numeric value in range 0-1000, 'ultra-condensed', 'extra-condensed', 'condensed', 'semi-condensed', 'normal', 'semi-expanded', 'expanded', 'extra-expanded', 'ultra-expanded'}
fontstyle
or style{'normal', 'italic', 'oblique'}
fontvariant
or variant{'normal', 'small-caps'}
fontweight
or weight{a numeric value in range 0-1000, 'ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'}
str
horizontalalignment
or ha{'left', 'center', 'right'}
bool
object
float (multiple of font size)
str
bool
multialignment
or ma{'left', 'right', 'center'}
bool
list of
AbstractPathEffect
None or bool or float or callable
(float, float)
bool
float or {'vertical', 'horizontal'}
{None, 'default', 'anchor'}
(scale: float, length: float, randomness: float)
bool or None
object
bool
str
bool or None
verticalalignment
or va{'baseline', 'bottom', 'center', 'center_baseline', 'top'}
bool
bool
float
float
float
- property visible_edges#
The cell edges to be drawn with a line.
Reading this property returns a substring of 'BRTL' (bottom, right, top, left').
When setting this property, you can use a substring of 'BRTL' or one of {'open', 'closed', 'horizontal', 'vertical'}.
- class matplotlib.table.Table(ax, loc=None, bbox=None, **kwargs)[source]#
Bases:
Artist
A table of cells.
The table consists of a grid of cells, which are indexed by (row, column).
For a simple table, you'll have a full grid of cells with indices from (0, 0) to (num_rows-1, num_cols-1), in which the cell (0, 0) is positioned at the top left. However, you can also add cells with negative indices. You don't have to add a cell to every grid position, so you can create tables that have holes.
Note: You'll usually not create an empty table from scratch. Instead use
table
to create a table from data.- Parameters:
- Other Parameters:
- **kwargs
Artist
properties.
- AXESPAD = 0.02#
The border between the Axes and the table edge in Axes units.
- FONTSIZE = 10#
- auto_set_column_width(col)[source]#
Automatically set the widths of given columns to optimal sizes.
- Parameters:
- colint or sequence of ints
The indices of the columns to auto-scale.
- codes = {'best': 0, 'bottom': 17, 'bottom left': 12, 'bottom right': 13, 'center': 9, 'center left': 5, 'center right': 6, 'left': 15, 'lower center': 7, 'lower left': 3, 'lower right': 4, 'right': 14, 'top': 16, 'top left': 11, 'top right': 10, 'upper center': 8, 'upper left': 2, 'upper right': 1}#
Possible values where to place the table relative to the Axes.
- contains(mouseevent)[source]#
Test whether the artist contains the mouse event.
- Parameters:
- mouseevent
MouseEvent
- mouseevent
- Returns:
- containsbool
Whether any values are within the radius.
- detailsdict
An artist-specific dictionary of details of the event context, such as which points are contained in the pick radius. See the individual Artist subclasses for details.
- draw(renderer)[source]#
Draw the Artist (and its children) using the given renderer.
This has no effect if the artist is not visible (
Artist.get_visible
returns False).- Parameters:
- renderer
RendererBase
subclass.
- renderer
Notes
This method is overridden in the Artist subclasses.
- property edges#
The default value of
visible_edges
for newly added cells usingadd_cell
.Notes
This setting does currently only affect newly created cells using
add_cell
.To change existing cells, you have to set their edges explicitly:
for c in tab.get_celld().values(): c.visible_edges = 'horizontal'
- get_celld()[source]#
Return a dict of cells in the table mapping (row, column) to
Cell
s.Notes
You can also directly index into the Table object to access individual cells:
cell = table[row, col]
- get_window_extent(renderer=None)[source]#
Get the artist's bounding box in display space.
The bounding box' width and height are nonnegative.
Subclasses should override for inclusion in the bounding box "tight" calculation. Default is to return an empty bounding box at 0, 0.
Be careful when using this function, the results will not update if the artist window extent of the artist changes. The extent can change due to any changes in the transform stack, such as changing the axes limits, the figure size, or the canvas used (as is done when saving a figure). This can lead to unexpected behavior where interactive figures will look fine on the screen, but will save incorrectly.
- set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, fontsize=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, mouseover=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)[source]#
Set multiple properties at once.
Supported properties are
Property
Description
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
scalar or None
bool
BboxBase
or Nonebool
Patch or (Path, Transform) or None
float
str
bool
object
bool
list of
AbstractPathEffect
None or bool or float or callable
bool
(scale: float, length: float, randomness: float)
bool or None
str
bool
float
- set_fontsize(size)[source]#
Set the font size, in points, of the cell text.
- Parameters:
- sizefloat
Notes
As long as auto font size has not been disabled, the value will be clipped such that the text fits horizontally into the cell.
You can disable this behavior using
auto_set_font_size
.>>> the_table.auto_set_font_size(False) >>> the_table.set_fontsize(20)
However, there is no automatic scaling of the row height so that the text may exceed the cell boundary.
- matplotlib.table.table(ax, cellText=None, cellColours=None, cellLoc='right', colWidths=None, rowLabels=None, rowColours=None, rowLoc='left', colLabels=None, colColours=None, colLoc='center', loc='bottom', bbox=None, edges='closed', **kwargs)[source]#
Add a table to an
Axes
.At least one of cellText or cellColours must be specified. These parameters must be 2D lists, in which the outer lists define the rows and the inner list define the column values per row. Each row must have the same number of elements.
The table can optionally have row and column headers, which are configured using rowLabels, rowColours, rowLoc and colLabels, colColours, colLoc respectively.
For finer grained control over tables, use the
Table
class and add it to the axes withAxes.add_table
.- Parameters:
- cellText2D list of str, optional
The texts to place into the table cells.
Note: Line breaks in the strings are currently not accounted for and will result in the text exceeding the cell boundaries.
- cellColours2D list of colors, optional
The background colors of the cells.
- cellLoc{'left', 'center', 'right'}, default: 'right'
The alignment of the text within the cells.
- colWidthslist of float, optional
The column widths in units of the axes. If not given, all columns will have a width of 1 / ncols.
- rowLabelslist of str, optional
The text of the row header cells.
- rowColourslist of colors, optional
The colors of the row header cells.
- rowLoc{'left', 'center', 'right'}, default: 'left'
The text alignment of the row header cells.
- colLabelslist of str, optional
The text of the column header cells.
- colColourslist of colors, optional
The colors of the column header cells.
- colLoc{'left', 'center', 'right'}, default: 'left'
The text alignment of the column header cells.
- locstr, optional
The position of the cell with respect to ax. This must be one of the
codes
.- bbox
Bbox
or [xmin, ymin, width, height], optional A bounding box to draw the table into. If this is not None, this overrides loc.
- edgessubstring of 'BRTL' or {'open', 'closed', 'horizontal', 'vertical'}
The cell edges to be drawn with a line. See also
visible_edges
.
- Returns:
Table
The created table.
- Other Parameters:
- **kwargs
Table
properties.Property
Description
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
scalar or None
bool
BboxBase
or Nonebool
Patch or (Path, Transform) or None
float
str
bool
object
bool
list of
AbstractPathEffect
None or bool or float or callable
bool
(scale: float, length: float, randomness: float)
bool or None
str
bool
float