TableReport#

class skrub.TableReport(dataframe, n_rows=None, order_by=None, title=None, column_filters=None, verbose=None, plot_distributions='auto', compute_associations='auto', open_tab='table', max_plot_columns=None, max_association_columns=None)[source]#

Summarize the contents of a dataframe.

This class summarizes a dataframe or numpy array, providing information such as the type and summary statistics (mean, number of missing values, etc.) for each column. Numpy arrays are converted to pandas DataFrame or Series. The computed statistics can be accessed interactively in a Jupyter notebook or web browser. Alternatively, it can be saved or exported in JSON, Markdown, or HTML format for programmatic access or for inclusion in documents.

Parameters:
dataframepandas or polars Series or DataFrame

The dataframe or series to summarize.

n_rowsint, default=None

Maximum number of rows to show in the sample table. Half will be taken from the beginning (head) of the dataframe and half from the end (tail). Note this is only for display. Summary statistics, histograms etc. are computed using the whole dataframe.

The default value None uses the global configuration (see set_config()), which then defaults to 10.

order_bystr, deprecated

Deprecated. Column name to use for sorting. Other numerical columns will be plotted as function of the sorting column. Must be of numerical or datetime type.

Deprecated since version 0.10.0.

titlestr

Title for the report.

column_filtersdict

A dict for adding custom entries to the column filter dropdown menu. Each key is the filter named to be displayed in the dropdown menu (e.g. "first_10"), and the value is the desired filter. Allowed formats for the filter values are a list of column names, a list of column indices, or a Selector object. See the end of the “Examples” section below for details.

verboseint, default = None

Whether to print progress information while the report is being generated.

  • verbose = None uses the global configuration (see set_config()), which then defaults to 1.

  • verbose = 1 prints how many columns have been processed so far.

  • verbose = 0 silences the output.

plot_distributionsbool or “auto”, default=”auto”

Whether to plot the distributions of the columns.

  • True: always generate plots, regardless of column count.

  • False: never generate plots.

  • "auto" (default): generate plots only when the number of columns does not exceed the configured table_report_plots_threshold (see set_config()).

compute_associationsbool or “auto”, default=”auto”

Whether to compute associations between columns.

  • True: always compute associations, regardless of column count.

  • False: never compute associations.

  • "auto" (default): compute associations only when the number of columns does not exceed the configured table_report_associations_threshold (see set_config()).

max_plot_columnsint or “all”, deprecated

Deprecated in favor of plot_distributions. This parameter overrides the value chosen for plot_distributions when it is not None.

Deprecated since version 0.9.0.

max_association_columnsint or “all”, deprecated

Deprecated in favor of compute_associations. This parameter overrides the value chosen for compute_associations when it is not None.

Deprecated since version 0.9.0.

open_tabstr, default=”table”

The tab that will be displayed by default when the report is opened. Must be one of “table”, “stats”, “distributions”, or “associations”.

  • “table”: Shows a sample of the dataframe rows

  • “stats”: Shows summary statistics for all columns

  • “distributions”: Shows plots of column distributions

  • “associations”: Shows column associations and similarities

See also

patch_display

Replace the default DataFrame HTML displays in the output of notebook cells with a TableReport.

Notes

You can see some example reports for a few datasets online. We also provide an experimental online demo that allows you to select a CSV or parquet file and generate a report directly in your web browser.

Examples

>>> import pandas as pd
>>> from skrub import TableReport
>>> df = pd.DataFrame(dict(a=[1, 2], b=['one', 'two'], c=[11.1, 11.1]))
>>> report = TableReport(df)

If you are in a Jupyter notebook, to display the report just have it be the last expression evaluated in a cell so that it is displayed in the cell’s output.

>>> report
<TableReport: use .open() or .markdown() to display>

(Note that above we only see the string representation, not the report itself, because we are not in a notebook.)

Whether you are using a notebook or not, you can always open the report as a full page in a separate browser tab with its open method: report.open().

You can also get the HTML report as a string with the html method or the html_snippet method. For a full, standalone web page:

>>> report.html()
'<!DOCTYPE html>\n<html lang="en-US">\n\n<head>\n    <meta charset="utf-8"...'

For an HTML fragment that can be inserted into a page:

>>> report.html_snippet()
'\n<div id="report_...-wrapper" hidden>\n    <template id="report_...'

If you want a summary of the report in plain-text format, you can use the markdown method to get a Markdown string that can be rendered in the notebook or used in Markdown documents. The string includes the summary statistics for all columns, so it can be quite long for dataframes with many columns.

>>> md = report.markdown()
>>> print(md)
# DataFrame Report...

The report can also be obtained in JSON format with json(), which can be useful for programmatic access to the report data. The schema of the JSON data is reported in TableReport JSON schema.

Note that the resulting JSON includes the plots in SVG format, which can be quite verbose: plots can be disabled by setting plot_distributions=False when generating the report:

>>> j = TableReport(df, plot_distributions=False).json()
>>> print(j)
{"dataframe_module": "pandas", "n_rows": 2, "n_columns": 3, "columns": ...

Advanced configuration: you can add custom column filters that will appear in the report’s dropdown menu, allowing you to select a subset of columns to display in the report.

>>> filters = {
...         "my_filter": ["a", "b"],
... }
>>> report = TableReport(df, column_filters=filters)

With the code above, in addition to the default filters such as “All columns”, “Numeric columns”, etc., the added “my_filter” will be available in the report, selecting both columns “a” and “b”. Filters may be specified as a list of column names, a list of column indices, or one of the skrub selectors objects.

Methods

dict()

Get the report data in Python Dictionary format.

html()

Get the report as a full HTML page.

html_snippet()

Get the report as an HTML fragment that can be inserted in a page.

json()

Get the report data in JSON format.

markdown()

Get the report as a Markdown string.

open()

Open the HTML report in a web browser.

write_html(file)

Store the report into an HTML file.
dict()[source]#

Get the report data in Python Dictionary format.

Returns:
dict

The report data

html()[source]#

Get the report as a full HTML page.

Returns:
str

The HTML page.

html_snippet()[source]#

Get the report as an HTML fragment that can be inserted in a page.

Returns:
str

The HTML snippet.

json()[source]#

Get the report data in JSON format.

By default, the JSON output includes the plots in SVG format, which can be quite verbose. Plots can be disabled by setting plot_distributions=False when generating the report.

The schema of the JSON data is reported in TableReport JSON schema.

Returns:
str

The JSON data.

markdown()[source]#

Get the report as a Markdown string.

This can be useful for displaying the report in environments that support Markdown for formatted text, to include the report in Markdown documents, or to get a quick text summary of the report.

Warning

The Markdown output can be provided to AI agents, but it does not perform any truncation or sanitization of the data. Therefore, it should not be used with untrusted data or in contexts where the data may be too large, as it could lead to performance issues or security risks.

Returns:
str

The Markdown report.

open()[source]#

Open the HTML report in a web browser.

write_html(file)[source]#

Store the report into an HTML file.

Parameters:
filestr, pathlib.Path or file object

The file object or path of the file to store the HTML output.