tablespam package

Subpackages

Submodules

tablespam.TableSpam module

TableSpam provides a formla-based syntax to define good-enough tables.

class tablespam.TableSpam.TableSpam(data: DataFrame, formula: str, title: str | None = None, subtitle: str | None = None, footnote: str | None = None)

Bases: object

Create complex table spanners with a simple formula.

tablespam provides a formula-based approach to adding headers and spanners to an existing polars DataFrame. The goal is to provide a unified, easy-to-use, but good-enough approach to building and exporting tables to Excel, HTML, and LaTeX. To this end, tablespam leverages the powerful packages openpyxl and great_tables.

The table headers are defined with a basic formula-inspired approach. For example, Species ~ Sepal_Length + Sepal_Width defines a table with Species as the row labels and Sepal_Length and Sepal_Width as columns. The output will look like:

| Species | Sepal_Length | Sepal_Width |
|:--------|-------------:|------------:|
| setosa  |          5.1 |         3.5 |
| setosa  |          4.9 |         3.0 |

Note that the row labels (Species) are in a separate block to the left.

You can add spanner labels as follows:

Species ~ (Sepal = Sepal_Length + Sepal_Width) + (Petal = Petal_Length + Petal_Width)

This results in an output like:

|         |      Sepal     |      Petal     |
| Species | Length | Width | Length | Width |
|:--------|-------:|------:|-------:|------:|
| setosa  |    5.1 |   3.5 |    1.4 |   0.2 |

Nested spanners can also be defined, e.g., Species ~ (Sepal = (Length = Sepal_Length) + (Width = Sepal_Width)).

When exporting tables, you can rename columns in the headers. For example, Species ~ (Sepal = Length:Sepal_Length + Width:Sepal_Width) creates:

|         |      Sepal     |      Petal     |
| Species | Length | Width | Length | Width |
|:--------|-------:|------:|-------:|------:|
| setosa  |    5.1 |   3.5 |    1.4 |   0.2 |

To create a table without row labels, use:

1 ~ (Sepal = Length:Sepal_Length + Width:Sepal_Width) + (Petal = Length:Petal_Length + Width:Petal_Width)

This creates:

|      Sepal     |      Petal     |
| Length | Width | Length | Width |
|-------:|------:|-------:|------:|
|    5.1 |   3.5 |    1.4 |   0.2 |

Tables created with tablespam can be exported to Excel (using openpyxl), HTML (using great_tables), and LaTeX (using great_tables).

References: - openpyxl: https://openpyxl.readthedocs.io/ - great_tables: https://posit-dev.github.io/great-tables/articles/intro.html

Examples

>>> from tablespam import TableSpam
>>> from tablespam.Data.mtcars import mtcars
>>> import polars as pl
>>> cars = mtcars()
>>> summarized_table = (
...     cars.group_by(['cyl', 'vs'])
...     .agg(
...         [
...             pl.len().alias('N'),
...             pl.col('hp').mean().alias('mean_hp'),
...             pl.col('hp').std().alias('sd_hp'),
...             pl.col('wt').mean().alias('mean_wt'),
...             pl.col('wt').std().alias('sd_wt'),
...         ]
...     )
...     .sort(['cyl', 'vs'])
... )
>>> tbl = TableSpam(
...     data=summarized_table,
...     formula='''Cylinder:cyl + Engine:vs ~
...                 N +
...                 (`Horse Power` = Mean:mean_hp + SD:sd_hp) +
...                 (`Weight` = Mean:mean_wt + SD:sd_wt)''',
...     title='Motor Trend Car Road Tests',
...     subtitle='A table created with tablespam',
...     footnote='Data from the infamous mtcars data set.',
... )
>>> print(tbl.as_string())
Motor Trend Car Road Tests
A table created with tablespam

|                 |     Horse Power       Weight      |
| Cylinder Engine | N   Mean        SD    Mean   SD   |
| -------- ------ - --- ----------- ----- ------ ---- |
| 4        0      | 1   91.0        None  2.14   None |
| 4        1      | 10  81.8        21.87 2.3    0.6  |
| 6        0      | 3   131.67      37.53 2.76   0.13 |
| ...      ...    | ... ...         ...   ...    ...  |
Data from the infamous mtcars data set.
as_excel(workbook: Workbook | None = None, sheet: str = 'Table', start_row: int = 1, start_col: int = 1, styles: XlsxStyles | None = None) → Workbook

Export a TableSpam table to Excel.

Tablespam uses openpyxl to export tables to Excel workbooks. See https://openpyxl.readthedocs.io/en/stable/ for more details on openpyxl.

Parameters:

  • workbook (opy.Workbook | None, optional) – An openpyxl workbook to which the table should be added. When set to None, a new workbook will be created. Defaults to None.

  • sheet (str, optional) – The name of the sheet to which the table should be written. Defaults to ‘Table’.

  • start_row (int, optional) – Index of the row where the table starts in the sheet. Defaults to 1.

  • start_col (int, optional) – Index of the column where the table starts in the sheet. Defaults to 1.

  • styles (XlsxStyles | None, optional) – Custom styles that are applied to the table. Defaults to None.

Returns:

openpyxl workbook

Return type:

opy.Workbook

Examples

>>> from tablespam import TableSpam
>>> from tablespam.Data.mtcars import mtcars
>>> import polars as pl
>>> cars = mtcars()
>>> summarized_table = (
...     cars.group_by(['cyl', 'vs'])
...     .agg(
...         [
...             pl.len().alias('N'),
...             pl.col('hp').mean().alias('mean_hp'),
...             pl.col('hp').std().alias('sd_hp'),
...             pl.col('wt').mean().alias('mean_wt'),
...             pl.col('wt').std().alias('sd_wt'),
...         ]
...     )
...     .sort(['cyl', 'vs'])
... )
>>> tbl = TableSpam(
...     data=summarized_table,
...     formula='''Cylinder:cyl + Engine:vs ~
...                 N +
...                 (`Horse Power` = Mean:mean_hp + SD:sd_hp) +
...                 (`Weight` = Mean:mean_wt + SD:sd_wt)''',
...     title='Motor Trend Car Road Tests',
...     subtitle='A table created with tablespam',
...     footnote='Data from the infamous mtcars data set.',
... )
>>> wb = tbl.as_excel()  # Export to Excel workbook
>>> # wb.save("tablespam_table.xlsx") # Write to an Excel file.
as_gt(separator_style: ~great_tables._styles.CellStyleBorders = CellStyleBorders(sides=['right'], color='gray', style='solid', weight='1px'), formatting: ~tablespam.GT._as_gt.as_gt.FormattingFunction | None = <function default_formatting>, groupname_col: str | None = None, auto_align: bool = True, id: str | None = None, locale: str | None = None) → GT

Translates a table created with tablespam into a gt table.

The tablespam library does not provide built-in support for rendering tables as HTML. However, with as_gt, a tablespam table can be converted into a gt table, which supports HTML and LaTeX output. For more details on gt, see <https://gt.rstudio.com/>.

Parameters:

  • groupname_col (str, optional) – Column names to group data. Refer to the gt documentation for details.

  • separator_style (str, optional) – Style of the vertical line separating row names from data.

  • formatting (function, optional) – This function is applied to the gt to format all columns.

  • auto_align (bool, optional) – Should the table entries be aligned automatically? See great_tables for more information

  • id (str, optional) – Id of the HTML table. See great_tables for more details

  • locale (str, optional) – affects formatting of dates and numbers. See great_tables for more details.

Returns:

A gt table object that can be further customized using the gt package.

Return type:

GtTable

Examples

>>> from tablespam import TableSpam
>>> from tablespam.Data.mtcars import mtcars
>>> import polars as pl
>>> cars = mtcars()
>>> summarized_table = (
...     cars.group_by(['cyl', 'vs'])
...     .agg(
...         [
...             pl.len().alias('N'),
...             pl.col('hp').mean().alias('mean_hp'),
...             pl.col('hp').std().alias('sd_hp'),
...             pl.col('wt').mean().alias('mean_wt'),
...             pl.col('wt').std().alias('sd_wt'),
...         ]
...     )
...     .sort(['cyl', 'vs'])
... )
>>> tbl = TableSpam(
...     data=summarized_table,
...     formula='''Cylinder:cyl + Engine:vs ~
...                 N +
...                 (`Horse Power` = Mean:mean_hp + SD:sd_hp) +
...                 (`Weight` = Mean:mean_wt + SD:sd_wt)''',
...     title='Motor Trend Car Road Tests',
...     subtitle='A table created with tablespam',
...     footnote='Data from the infamous mtcars data set.',
... )
>>> gt_tbl = tbl.as_gt()
>>> # Use tbl.as_gt().show() to show the table in the browser.
as_string(digits: int = 2, n: int = 3, max_char: int = 30) → str

Translates a table to string.

The main purpose if this transformation is for debugging. Exporting to gt or excel are more feature complete.

Parameters:

  • digits (int, optional) – Number of digits to round floats to. Defaults to 2.

  • n (int, optional) – number of rows from the data set to print. Defaults to 3.

  • max_char (int, optional) – number of characters that each cell at maximum is allows to have. Defaults to 30.

Returns:

String describing the table

Return type:

str

Examples

>>> from tablespam import TableSpam
>>> from tablespam.Data.mtcars import mtcars
>>> import polars as pl
>>> cars = mtcars()
>>> summarized_table = (
...     cars.group_by(['cyl', 'vs'])
...     .agg(
...         [
...             pl.len().alias('N'),
...             pl.col('hp').mean().alias('mean_hp'),
...             pl.col('hp').std().alias('sd_hp'),
...             pl.col('wt').mean().alias('mean_wt'),
...             pl.col('wt').std().alias('sd_wt'),
...         ]
...     )
...     .sort(['cyl', 'vs'])
... )
>>> tbl = TableSpam(
...     data=summarized_table,
...     formula='''Cylinder:cyl + Engine:vs ~
...                 N +
...                 (`Horse Power` = Mean:mean_hp + SD:sd_hp) +
...                 (`Weight` = Mean:mean_wt + SD:sd_wt)''',
...     title='Motor Trend Car Road Tests',
...     subtitle='A table created with tablespam',
...     footnote='Data from the infamous mtcars data set.',
... )
>>> print(tbl.as_string())
Motor Trend Car Road Tests
A table created with tablespam

|                 |     Horse Power       Weight      |
| Cylinder Engine | N   Mean        SD    Mean   SD   |
| -------- ------ - --- ----------- ----- ------ ---- |
| 4        0      | 1   91.0        None  2.14   None |
| 4        1      | 10  81.8        21.87 2.3    0.6  |
| 6        0      | 3   131.67      37.53 2.76   0.13 |
| ...      ...    | ... ...         ...   ...    ...  |
Data from the infamous mtcars data set.
tablespam.TableSpam.select_data(data: DataFrame, variables: list[str]) → DataFrame | None

Subsets the data frame to only the relevant variables.

Parameters:

  • data (pl.DataFrame) – polars data frame that should be subsetted

  • variables (list[str]) – list with names of items that should be retained

Returns:

polars data frame with the specified variables

Return type:

pl.DataFrame | None

Module contents

Create satisficing tables with tablespam.

Tablespam is a very basic package with a sole objective: To simplify creating tables that are “good enough” for many purposes and that can easily be exported to a variety of formats. To this end, tablespam leverages the awesome packages great_tables (https://posit-dev.github.io/great-tables/articles/intro.html) and openpyxl (https://openpyxl.readthedocs.io/en/stable/).

class tablespam.CellStyle(rows: list[int], cols: list[str], style: Callable[[Cell], None])

Bases: object

Cell styles are styles that are applied to specific cells in the data.

A cell style is defined by a list of row indexed, a list of column names, and a style. The style is a function that formats single cells of an openpyxl workbook.

Example

>>> from tablespam.Excel.xlsx_styles import CellStyle
>>> style = CellStyle(
...     rows=[1, 2],
...     cols=['column_1'],
...     style=lambda c: setattr(c, 'number_format', '0.00'),
... )
cols: list[str]
rows: list[int]
style: Callable[[Cell], None]
class tablespam.DataStyle(test: Callable[[DataFrame], bool], style: Callable[[Cell], None])

Bases: object

Data styles are styles that are applied to all columns of a specific type.

Each DataStyle is a combination of a test and a style.

The test is a function that is applied to the data column. It should check if the column is of a specific type and return either True or False.

The style is a function that is applied to a single cell in an openpyxl workbook and adds styling to that cell.

Example

>>> import polars as pl
>>> from tablespam.Excel.xlsx_styles import DataStyle
>>> # Define a test that checks if a single data column is of type double:
>>> def test_double(x: pl.DataFrame):
...     if len(x.columns) != 1:
...         raise ValueError('Multiple columns passed to test.')
...     return all([tp in [pl.Float32, pl.Float64] for tp in x.dtypes])
>>> style = DataStyle(
...     test=test_double, style=lambda c: setattr(c, 'number_format', '0.00')
... )
style: Callable[[Cell], None]
test: Callable[[DataFrame], bool]
class tablespam.TableSpam(data: DataFrame, formula: str, title: str | None = None, subtitle: str | None = None, footnote: str | None = None)

Bases: object

Create complex table spanners with a simple formula.

tablespam provides a formula-based approach to adding headers and spanners to an existing polars DataFrame. The goal is to provide a unified, easy-to-use, but good-enough approach to building and exporting tables to Excel, HTML, and LaTeX. To this end, tablespam leverages the powerful packages openpyxl and great_tables.

The table headers are defined with a basic formula-inspired approach. For example, Species ~ Sepal_Length + Sepal_Width defines a table with Species as the row labels and Sepal_Length and Sepal_Width as columns. The output will look like:

| Species | Sepal_Length | Sepal_Width |
|:--------|-------------:|------------:|
| setosa  |          5.1 |         3.5 |
| setosa  |          4.9 |         3.0 |

Note that the row labels (Species) are in a separate block to the left.

You can add spanner labels as follows:

Species ~ (Sepal = Sepal_Length + Sepal_Width) + (Petal = Petal_Length + Petal_Width)

This results in an output like:

|         |      Sepal     |      Petal     |
| Species | Length | Width | Length | Width |
|:--------|-------:|------:|-------:|------:|
| setosa  |    5.1 |   3.5 |    1.4 |   0.2 |

Nested spanners can also be defined, e.g., Species ~ (Sepal = (Length = Sepal_Length) + (Width = Sepal_Width)).

When exporting tables, you can rename columns in the headers. For example, Species ~ (Sepal = Length:Sepal_Length + Width:Sepal_Width) creates:

|         |      Sepal     |      Petal     |
| Species | Length | Width | Length | Width |
|:--------|-------:|------:|-------:|------:|
| setosa  |    5.1 |   3.5 |    1.4 |   0.2 |

To create a table without row labels, use:

1 ~ (Sepal = Length:Sepal_Length + Width:Sepal_Width) + (Petal = Length:Petal_Length + Width:Petal_Width)

This creates:

|      Sepal     |      Petal     |
| Length | Width | Length | Width |
|-------:|------:|-------:|------:|
|    5.1 |   3.5 |    1.4 |   0.2 |

Tables created with tablespam can be exported to Excel (using openpyxl), HTML (using great_tables), and LaTeX (using great_tables).

References: - openpyxl: https://openpyxl.readthedocs.io/ - great_tables: https://posit-dev.github.io/great-tables/articles/intro.html

Examples

>>> from tablespam import TableSpam
>>> from tablespam.Data.mtcars import mtcars
>>> import polars as pl
>>> cars = mtcars()
>>> summarized_table = (
...     cars.group_by(['cyl', 'vs'])
...     .agg(
...         [
...             pl.len().alias('N'),
...             pl.col('hp').mean().alias('mean_hp'),
...             pl.col('hp').std().alias('sd_hp'),
...             pl.col('wt').mean().alias('mean_wt'),
...             pl.col('wt').std().alias('sd_wt'),
...         ]
...     )
...     .sort(['cyl', 'vs'])
... )
>>> tbl = TableSpam(
...     data=summarized_table,
...     formula='''Cylinder:cyl + Engine:vs ~
...                 N +
...                 (`Horse Power` = Mean:mean_hp + SD:sd_hp) +
...                 (`Weight` = Mean:mean_wt + SD:sd_wt)''',
...     title='Motor Trend Car Road Tests',
...     subtitle='A table created with tablespam',
...     footnote='Data from the infamous mtcars data set.',
... )
>>> print(tbl.as_string())
Motor Trend Car Road Tests
A table created with tablespam

|                 |     Horse Power       Weight      |
| Cylinder Engine | N   Mean        SD    Mean   SD   |
| -------- ------ - --- ----------- ----- ------ ---- |
| 4        0      | 1   91.0        None  2.14   None |
| 4        1      | 10  81.8        21.87 2.3    0.6  |
| 6        0      | 3   131.67      37.53 2.76   0.13 |
| ...      ...    | ... ...         ...   ...    ...  |
Data from the infamous mtcars data set.
as_excel(workbook: Workbook | None = None, sheet: str = 'Table', start_row: int = 1, start_col: int = 1, styles: XlsxStyles | None = None) → Workbook

Export a TableSpam table to Excel.

Tablespam uses openpyxl to export tables to Excel workbooks. See https://openpyxl.readthedocs.io/en/stable/ for more details on openpyxl.

Parameters:

  • workbook (opy.Workbook | None, optional) – An openpyxl workbook to which the table should be added. When set to None, a new workbook will be created. Defaults to None.

  • sheet (str, optional) – The name of the sheet to which the table should be written. Defaults to ‘Table’.

  • start_row (int, optional) – Index of the row where the table starts in the sheet. Defaults to 1.

  • start_col (int, optional) – Index of the column where the table starts in the sheet. Defaults to 1.

  • styles (XlsxStyles | None, optional) – Custom styles that are applied to the table. Defaults to None.

Returns:

openpyxl workbook

Return type:

opy.Workbook

Examples

>>> from tablespam import TableSpam
>>> from tablespam.Data.mtcars import mtcars
>>> import polars as pl
>>> cars = mtcars()
>>> summarized_table = (
...     cars.group_by(['cyl', 'vs'])
...     .agg(
...         [
...             pl.len().alias('N'),
...             pl.col('hp').mean().alias('mean_hp'),
...             pl.col('hp').std().alias('sd_hp'),
...             pl.col('wt').mean().alias('mean_wt'),
...             pl.col('wt').std().alias('sd_wt'),
...         ]
...     )
...     .sort(['cyl', 'vs'])
... )
>>> tbl = TableSpam(
...     data=summarized_table,
...     formula='''Cylinder:cyl + Engine:vs ~
...                 N +
...                 (`Horse Power` = Mean:mean_hp + SD:sd_hp) +
...                 (`Weight` = Mean:mean_wt + SD:sd_wt)''',
...     title='Motor Trend Car Road Tests',
...     subtitle='A table created with tablespam',
...     footnote='Data from the infamous mtcars data set.',
... )
>>> wb = tbl.as_excel()  # Export to Excel workbook
>>> # wb.save("tablespam_table.xlsx") # Write to an Excel file.
as_gt(separator_style: ~great_tables._styles.CellStyleBorders = CellStyleBorders(sides=['right'], color='gray', style='solid', weight='1px'), formatting: ~tablespam.GT._as_gt.as_gt.FormattingFunction | None = <function default_formatting>, groupname_col: str | None = None, auto_align: bool = True, id: str | None = None, locale: str | None = None) → GT

Translates a table created with tablespam into a gt table.

The tablespam library does not provide built-in support for rendering tables as HTML. However, with as_gt, a tablespam table can be converted into a gt table, which supports HTML and LaTeX output. For more details on gt, see <https://gt.rstudio.com/>.

Parameters:

  • groupname_col (str, optional) – Column names to group data. Refer to the gt documentation for details.

  • separator_style (str, optional) – Style of the vertical line separating row names from data.

  • formatting (function, optional) – This function is applied to the gt to format all columns.

  • auto_align (bool, optional) – Should the table entries be aligned automatically? See great_tables for more information

  • id (str, optional) – Id of the HTML table. See great_tables for more details

  • locale (str, optional) – affects formatting of dates and numbers. See great_tables for more details.

Returns:

A gt table object that can be further customized using the gt package.

Return type:

GtTable

Examples

>>> from tablespam import TableSpam
>>> from tablespam.Data.mtcars import mtcars
>>> import polars as pl
>>> cars = mtcars()
>>> summarized_table = (
...     cars.group_by(['cyl', 'vs'])
...     .agg(
...         [
...             pl.len().alias('N'),
...             pl.col('hp').mean().alias('mean_hp'),
...             pl.col('hp').std().alias('sd_hp'),
...             pl.col('wt').mean().alias('mean_wt'),
...             pl.col('wt').std().alias('sd_wt'),
...         ]
...     )
...     .sort(['cyl', 'vs'])
... )
>>> tbl = TableSpam(
...     data=summarized_table,
...     formula='''Cylinder:cyl + Engine:vs ~
...                 N +
...                 (`Horse Power` = Mean:mean_hp + SD:sd_hp) +
...                 (`Weight` = Mean:mean_wt + SD:sd_wt)''',
...     title='Motor Trend Car Road Tests',
...     subtitle='A table created with tablespam',
...     footnote='Data from the infamous mtcars data set.',
... )
>>> gt_tbl = tbl.as_gt()
>>> # Use tbl.as_gt().show() to show the table in the browser.
as_string(digits: int = 2, n: int = 3, max_char: int = 30) → str

Translates a table to string.

The main purpose if this transformation is for debugging. Exporting to gt or excel are more feature complete.

Parameters:

  • digits (int, optional) – Number of digits to round floats to. Defaults to 2.

  • n (int, optional) – number of rows from the data set to print. Defaults to 3.

  • max_char (int, optional) – number of characters that each cell at maximum is allows to have. Defaults to 30.

Returns:

String describing the table

Return type:

str

Examples

>>> from tablespam import TableSpam
>>> from tablespam.Data.mtcars import mtcars
>>> import polars as pl
>>> cars = mtcars()
>>> summarized_table = (
...     cars.group_by(['cyl', 'vs'])
...     .agg(
...         [
...             pl.len().alias('N'),
...             pl.col('hp').mean().alias('mean_hp'),
...             pl.col('hp').std().alias('sd_hp'),
...             pl.col('wt').mean().alias('mean_wt'),
...             pl.col('wt').std().alias('sd_wt'),
...         ]
...     )
...     .sort(['cyl', 'vs'])
... )
>>> tbl = TableSpam(
...     data=summarized_table,
...     formula='''Cylinder:cyl + Engine:vs ~
...                 N +
...                 (`Horse Power` = Mean:mean_hp + SD:sd_hp) +
...                 (`Weight` = Mean:mean_wt + SD:sd_wt)''',
...     title='Motor Trend Car Road Tests',
...     subtitle='A table created with tablespam',
...     footnote='Data from the infamous mtcars data set.',
... )
>>> print(tbl.as_string())
Motor Trend Car Road Tests
A table created with tablespam

|                 |     Horse Power       Weight      |
| Cylinder Engine | N   Mean        SD    Mean   SD   |
| -------- ------ - --- ----------- ----- ------ ---- |
| 4        0      | 1   91.0        None  2.14   None |
| 4        1      | 10  81.8        21.87 2.3    0.6  |
| 6        0      | 3   131.67      37.53 2.76   0.13 |
| ...      ...    | ... ...         ...   ...    ...  |
Data from the infamous mtcars data set.
class tablespam.XlsxStyles(bg_default: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function default_bg_style>, bg_title: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function default_bg_style>, bg_subtitle: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function default_bg_style>, bg_header_lhs: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function default_bg_style>, bg_header_rhs: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function default_bg_style>, bg_rownames: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function default_bg_style>, bg_data: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function default_bg_style>, bg_footnote: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function default_bg_style>, vline: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function vline_style>, hline: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function hline_style>, cell_title: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function cell_title_style>, cell_subtitle: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function cell_subtitle_style>, cell_header_lhs: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function cell_header_lhs_style>, cell_header_rhs: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function cell_header_rhs_style>, cell_rownames: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function cell_rownames_style>, cell_data: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function cell_data_style>, cell_footnote: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function cell_footnote_style>, merge_rownames: bool = True, merged_rownames_style: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function merged_rownames_style>, footnote_style: ~typing.Callable[[~openpyxl.cell.cell.Cell], None] = <function footnote_style>, data_styles: dict[str, ~tablespam.Excel.xlsx_styles.DataStyle] = <factory>, cell_styles: None | list[~tablespam.Excel.xlsx_styles.CellStyle] = None)

Bases: object

Defines styles for different elements of the table.

Each style element is a function that takes in a single cell of the openpyxl workbook and apply a style to that cell.

Parameters:

  • merge_rownames (bool) – Should adjacent rows with identical names be merged?

  • merged_rownames_style (Callable[[Cell], None]) – style applied to the merged rownames

  • footnote_style (Callable[[Cell], None]) – style applied to the table footnote

  • data_styles (Callable[[Cell], None]) – styles applied to the columns in the data set based on their classes (e.g., numeric, character, etc.). data_styles must be a dict of DataStyle. Note that styles will be applied in the order of the list, meaning that a later style may overwrite an earlier style.

  • cell_styles (list[CellStyle]) – an optional list with styles for selected cells in the data frame.

  • bg_default (Callable[[Cell], None]) – default color for the background of the table

  • bg_title (Callable[[Cell], None]) – background color for the title

  • bg_subtitle (Callable[[Cell], None]) – background color for the subtitle

  • bg_header_lhs (Callable[[Cell], None]) – background color for the left hand side of the table header

  • bg_header_rhs (Callable[[Cell], None]) – background color for the right hand side of the table header

  • bg_rownames (Callable[[Cell], None]) – background color for the row names

  • bg_data (Callable[[Cell], None]) – background color for the data

  • bg_footnote (Callable[[Cell], None]) – background color for the footnote

  • vline (Callable[[Cell], None]) – styling for all vertical lines added to the table

  • hline (Callable[[Cell], None]) – styling for all horizontal lines added to the table

  • cell_default (Callable[[Cell], None]) – default style added to cells in the table

  • cell_title (Callable[[Cell], None]) – style added to title cells in the table

  • cell_subtitle (Callable[[Cell], None]) – style added to subtitle cells in the table

  • cell_header_lhs (Callable[[Cell], None]) – style added to the left hand side of the header cells in the table

  • cell_header_rhs (Callable[[Cell], None]) – style added to the right hand side of the header cells in the table

  • cell_rownames (Callable[[Cell], None]) – style added to row name cells in the table

  • cell_data (Callable[[Cell], None]) – style added to data cells in the table

  • cell_footnote (Callable[[Cell], None]) – style added to footnote cells in the table

bg_data() → None

Default background style.

Parameters:

cell (Cell) – Cell reference to which the style is applied

bg_default() → None

Default background style.

Parameters:

cell (Cell) – Cell reference to which the style is applied

bg_footnote() → None

Default background style.

Parameters:

cell (Cell) – Cell reference to which the style is applied

bg_header_lhs() → None

Default background style.

Parameters:

cell (Cell) – Cell reference to which the style is applied

bg_header_rhs() → None

Default background style.

Parameters:

cell (Cell) – Cell reference to which the style is applied

bg_rownames() → None

Default background style.

Parameters:

cell (Cell) – Cell reference to which the style is applied

bg_subtitle() → None

Default background style.

Parameters:

cell (Cell) – Cell reference to which the style is applied

bg_title() → None

Default background style.

Parameters:

cell (Cell) – Cell reference to which the style is applied

cell_data() → None

Default style applied to data cells.

Parameters:

cell (Cell) – Cell reference to which the style is applied

cell_footnote() → None

Default style applied to footnote cells.

Parameters:

cell (Cell) – Cell reference to which the style is applied

cell_header_lhs() → None

Default style applied to left hand side of the table header.

Parameters:

cell (Cell) – Cell reference to which the style is applied

cell_header_rhs() → None

Default style applied to right hand side of the table header.

Parameters:

cell (Cell) – Cell reference to which the style is applied

cell_rownames() → None

Default style applied to rowname cells.

Parameters:

cell (Cell) – Cell reference to which the style is applied

cell_styles: None | list[CellStyle] = None
cell_subtitle() → None

Default subtitle style.

Parameters:

cell (Cell) – Cell reference to which the style is applied

cell_title() → None

Default title cell style.

Parameters:

cell (Cell) – Cell reference to which the style is applied

data_styles: dict[str, DataStyle]
footnote_style() → None

Default style applied to footnote.

Parameters:

cell (Cell) – Cell reference to which the style is applied

hline() → None

Default horizontal line style.

Parameters:

cell (Cell) – Cell reference to which the style is applied

merge_rownames: bool = True
merged_rownames_style() → None

Default style applied to merged row name cells.

Parameters:

cell (Cell) – Cell reference to which the style is applied

vline() → None

Default vertical line style.

Parameters:

cell (Cell) – Cell reference to which the style is applied

tablespam.default_formatting(gt_tbl: GT, decimals: int = 2) → GT

Provides a default formatting for all columns in the great table.

Parameters:

  • gt_tbl (gt.GT) – Great table before formatting

  • decimals (int, optional) – The number of decimals to round floats to. Defaults to 2.

Returns:

Great table after formatting

Return type:

gt.GT

tablespam.style_color(primary_color: str = 'ffffff') → XlsxStyles

Provides a simple way to define a color scheme for tables.

By default, tables have a “light” theme, where the background is white and text / lines are black. Based on a primary color, style_color will create tables that use the primary color as background for all title, header, and row name cells and adapts the text color based on the primary color. The automatic adaption of the background color is implemented based on Mark Ransom and SudoPlz at <https://stackoverflow.com/questions/3942878/how-to-decide-font-color-in-white-or-black-depending-on-background-color>

Parameters:

primary_color (str, optional) – olor to be used for the title, header, and row names background. This must be a hex code for the color. Defaults to ‘ffffff’.

Returns:

Style object

Return type:

XlsxStyles