matplotlib.table¶
This module provides functionality to add a table to a plot.
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)[source]¶
Bases: matplotlib.patches.Rectangle
A cell is a Rectangle with some associated Text.
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.
Parameters: - xy(float, float)
The bottom and left rectangle coordinates
- widthfloat
Rectangle width
- heightfloat
Rectangle height
- anglefloat, optional
rotation in degrees anti-clockwise about xy (default is 0.0)
- fillbool, optional
Whether to fill the rectangle (default is True)
Notes
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 float or None animated bool antialiased or aa unknown capstyle {'butt', 'round', 'projecting'} clip_box Bbox clip_on bool clip_path Patch or (Path, Transform) or None color color contains callable edgecolor or ec color or None or 'auto' facecolor or fc color or None figure Figure fill bool gid str hatch {'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} in_layout bool joinstyle {'miter', 'round', 'bevel'} label object linestyle or ls {'-', '--', '-.', ':', '', (offset, on-off-seq), ...} linewidth or lw float or None path_effects AbstractPathEffect picker None or bool or float or callable rasterized bool or None sketch_params (scale: float, length: float, randomness: float) snap bool or None transform Transform url str visible bool zorder float - PAD = 0.1¶
Padding between text and rectangle.
- auto_set_font_size(self, renderer)[source]¶
Shrink font size until the text fits into the cell width.
- get_text_bounds(self, renderer)[source]¶
Return the text bounds as (x, y, width, height) in table coordinates.
- set_text_props(self, **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 float 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 c color contains callable figure Figure fontfamily or family {FONTNAME, 'serif', 'sans-serif', 'cursive', 'fantasy', 'monospace'} fontproperties or font_properties font_manager.FontProperties fontsize or size {size in points, '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) multialignment or ma {'left', 'right', 'center'} path_effects AbstractPathEffect picker None or bool or float or callable position (float, float) rasterized bool or None rotation {angle in degrees, 'vertical', 'horizontal'} rotation_mode {None, 'default', 'anchor'} sketch_params (scale: float, length: float, randomness: float) snap bool or None text object transform Transform 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
- class matplotlib.table.CustomCell(*args, visible_edges, **kwargs)[source]¶
Bases: matplotlib.table.Cell
A Cell subclass with configurable edge visibility.
Parameters: - xy(float, float)
The bottom and left rectangle coordinates
- widthfloat
Rectangle width
- heightfloat
Rectangle height
- anglefloat, optional
rotation in degrees anti-clockwise about xy (default is 0.0)
- fillbool, optional
Whether to fill the rectangle (default is True)
Notes
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 float or None animated bool antialiased or aa unknown capstyle {'butt', 'round', 'projecting'} clip_box Bbox clip_on bool clip_path Patch or (Path, Transform) or None color color contains callable edgecolor or ec color or None or 'auto' facecolor or fc color or None figure Figure fill bool gid str hatch {'/', '\', '|', '-', '+', 'x', 'o', 'O', '.', '*'} in_layout bool joinstyle {'miter', 'round', 'bevel'} label object linestyle or ls {'-', '--', '-.', ':', '', (offset, on-off-seq), ...} linewidth or lw float or None path_effects AbstractPathEffect picker None or bool or float or callable rasterized bool or None sketch_params (scale: float, length: float, randomness: float) snap bool or None transform Transform url str visible bool zorder float - get_path(self)[source]¶
Return a Path for the visible_edges.
- 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: 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: - axmatplotlib.axes.Axes
The Axes to plot the table into.
- locstr
The position of the cell with respect to ax. This must be one of the codes.
- bboxBbox 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(self, row, col, *args, **kwargs)[source]¶
Create a cell and add it to the table.
Parameters: - rowint
Row index.
- colint
Column index.
- *args, **kwargs
All other parameters are passed on to Cell.
Returns: - cellCustomCell
The created cell.
- auto_set_column_width(self, 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(self, mouseevent)[source]¶
Test whether the artist contains the mouse event.
Parameters: - mouseeventmatplotlib.backend_bases.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.
See also
- set_contains, get_contains
- draw(self, renderer)[source]¶
Draw the Artist using the given renderer.
This method will be overridden in the Artist subclasses. Typically, it is implemented to not have any effect if the Artist is not visible (Artist.get_visible is False).
Parameters: - rendererRendererBase subclass.
- property edges¶
The default value of visible_edges for newly added cells using add_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(self)[source]¶
Return a dict of cells in the table mapping (row, column) to Cells.
Notes
You can also directly index into the Table object to access individual cells:
cell = table[row, col]
- set_fontsize(self, 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 with Axes.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'}, optional, 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'}, optional, 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.
- bboxBbox, 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: - tableTable
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 float or None animated bool clip_box Bbox clip_on bool clip_path Patch or (Path, Transform) or None contains callable figure Figure fontsize float gid str in_layout bool label object path_effects AbstractPathEffect picker None or bool or float or callable rasterized bool or None sketch_params (scale: float, length: float, randomness: float) snap bool or None transform Transform url str visible bool zorder float