matplotlib.table
Tables drawing.
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:
matplotlib.patches.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: - xy 2-tuple
-
The position of the bottom left corner of the cell.
- width float
-
The cell width.
- height float
-
The cell height.
- edgecolor color
-
The color of the cell border.
- facecolor color
-
The cell facecolor.
- fill bool
-
Whether the cell background is filled.
- text str
-
The cell text.
- loc {'left', 'center', 'right'}, default: 'right'
-
The alignment of the text within the cell.
- fontproperties dict
-
A dict defining the font properties of the text. Supported keys and values are the keyword arguments accepted by
FontProperties
. - visible_edges str, 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.
-
auto_set_font_size
( renderer ) [source] -
Shrink font size until the text fits into the cell width.
-
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.
Notes
This method is overridden in the Artist subclasses.
-
renderer
-
get_fontsize
( ) [source] -
Return the cell fontsize.
-
get_path
( ) [source] -
Return a
Path
for thevisible_edges
.
-
get_required_width
( renderer ) [source] -
Return the minimal required width for the cell.
-
get_text_bounds
( renderer ) [source] -
Return the text bounds as (x, y, width, height) in table coordinates.
-
set_fontsize
( size ) [source] -
Set the text fontsize.
-
set_text_props
( **kwargs ) [source] -
Update the text properties.
Valid keyword arguments are:
Property Description agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array alpha
scalar or None animated
bool backgroundcolor
color bbox
dict with properties for patches.FancyBboxPatch
clip_box
Bbox
clip_on
bool clip_path
Patch or (Path, Transform) or None color
or ccolor contains
unknown figure
Figure
fontfamily
or family{FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'} fontproperties
or font or font_propertiesfont_manager.FontProperties
orstr
orpathlib.Path
fontsize
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'} gid
str horizontalalignment
or ha{'center', 'right', 'left'} in_layout
bool label
object linespacing
float (multiple of font size) math_fontfamily
str multialignment
or ma{'left', 'right', 'center'} path_effects
AbstractPathEffect
picker
None or bool or float or callable position
(float, float) rasterized
bool rotation
float or {'vertical', 'horizontal'} rotation_mode
{None, 'default', 'anchor'} sketch_params
(scale: float, length: float, randomness: float) snap
bool or None text
object transform
Transform
transform_rotates_text
bool url
str usetex
bool or None verticalalignment
or va{'center', 'top', 'bottom', 'baseline', 'center_baseline'} visible
bool wrap
bool x
float y
float zorder
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'}.
-
matplotlib.table.
CustomCell
-
alias of
matplotlib.table.Cell
-
class
matplotlib.table.
Table
( ax, loc=None, bbox=None, **kwargs ) [source] -
Bases:
matplotlib.artist.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: -
ax
matplotlib.axes.Axes
-
The
Axes
to plot the table into. - loc str
-
The position of the cell with respect to ax. This must be one of the
codes
. -
bbox
Bbox
or None -
A bounding box to draw the table into. If this is not None, this overrides loc.
Other Parameters: - **kwargs
-
Artist
properties.
-
AXESPAD
= 0.02 -
The border between the Axes and the table edge in Axes units.
-
FONTSIZE
= 10
-
add_cell
( row, col, *args, **kwargs ) [source] -
Create a cell and add it to the table.
Parameters: - row int
-
Row index.
- col int
-
Column index.
- *args, **kwargs
-
All other parameters are passed on to
Cell
.
Returns: -
Cell
-
The created cell.
-
auto_set_column_width
( col ) [source] -
Automatically set the widths of given columns to optimal sizes.
Parameters: - col int or sequence of ints
-
The indices of the columns to auto-scale.
-
auto_set_font_size
( value=True ) [source] -
Automatically set font size.
-
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
matplotlib.backend_bases.MouseEvent
Returns: - contains bool
-
Whether any values are within the radius.
- details dict
-
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.
-
mouseevent
-
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.
Notes
This method is overridden in the Artist subclasses.
-
renderer
-
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_children
( ) [source] -
Return the Artists contained by the table.
-
get_window_extent
( renderer ) [source] -
Return the bounding box of the table in window coords.
-
scale
( xscale, yscale ) [source] -
Scale column widths by xscale and row heights by yscale.
-
set_fontsize
( size ) [source] -
Set the font size, in points, of the cell text.
Parameters: - size float
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.
-
ax
-
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: - cellText 2D 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.
- cellColours 2D list of colors, optional
-
The background colors of the cells.
- cellLoc {'left', 'center', 'right'}, default: 'right'
-
The alignment of the text within the cells.
- colWidths list of float, optional
-
The column widths in units of the axes. If not given, all columns will have a width of 1 / ncols.
- rowLabels list of str, optional
-
The text of the row header cells.
- rowColours list of colors, optional
-
The colors of the row header cells.
- rowLoc {'left', 'center', 'right'}, default: 'left'
-
The text alignment of the row header cells.
- colLabels list of str, optional
-
The text of the column header cells.
- colColours list of colors, optional
-
The colors of the column header cells.
- colLoc {'left', 'center', 'right'}, default: 'left'
-
The text alignment of the column header cells.
- loc str, optional
-
The position of the cell with respect to ax. This must be one of the
codes
. -
bbox
Bbox
, optional -
A bounding box to draw the table into. If this is not None, this overrides loc.
- edges substring 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 agg_filter
a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array alpha
scalar or None animated
bool clip_box
Bbox
clip_on
bool clip_path
Patch or (Path, Transform) or None contains
unknown figure
Figure
fontsize
float gid
str in_layout
bool label
object path_effects
AbstractPathEffect
picker
None or bool or float or callable rasterized
bool sketch_params
(scale: float, length: float, randomness: float) snap
bool or None transform
Transform
url
str visible
bool zorder
float
© 2012–2021 Matplotlib Development Team. All rights reserved.
Licensed under the Matplotlib License Agreement.
https://matplotlib.org/3.4.3/api/table_api.html