feat: support `style.*()` from Great Tables

[jrycw]

Great Tables provides several style.*() functions that simplify table styling.

I'd like to suggest exploring whether gt-extras could support these functions.

For instance, style.fill() is a great candidate. Allowing it to be passed to the fill= or background= parameters would enable users to specify colors using from_column() or Polars expressions — an idiomatic approach, in my opinion.

[juleswg23]

Sorry this slipped through the cracks. I think in principle this would be nice and cohesive, and since it wouldn't break any existing behavior I would be happy to work on a PR with you. Because it doesn't necessarily add anything that cannot already be accomplished, I will probably not take the lead on it, but would still proceed if you wanted to.

My biggest concern is the implementation isn't as direct as it is in Great Tables. The _to_html_style methods in _styles.py in Great Tables generate html (see below), while the application of styling in gt-extras is inside SVGs (as of #147). I haven't really thought about implementation details here, but at first glance I would guess this would involve a decent amount of setup work.

def _to_html_style(self) -> str:
  return f"background-color: {self.color};"

[jrycw]

Thanks for the response, and sorry for the late reply.

I came up with a solution from a different perspective.

The main idea is to resolve the cell in advance to obtain the actual value of the color column.

Here's the draft code (assume it is in the _utils_style.py module):

from typing import TYPE_CHECKING

from great_tables._gt_data import GTData, StyleInfo
from great_tables._locations import LocBody, resolve, CellPos, resolve_cols_c
from great_tables._styles import CellStyleFill, FromColumn
from great_tables._tbl_data import PlExpr


if TYPE_CHECKING:
    import polars as pl
    PlExpr = pl.Expr

def get_style_fill_info(data: GTData, style: CellStyleFill) -> list[StyleInfo]:
    style_color = style.color
    if isinstance(style_color, FromColumn):
        color_column: str = style_color.column
    elif isinstance(style_color, PlExpr):
        color_column: str = resolve_cols_c(data=data, expr=style_color)[0]

    loc = LocBody(columns=color_column)
    positions: list[CellPos] = resolve(loc, data)
    style_ready = style._evaluate_expressions(data._tbl_data)

    all_info: list[StyleInfo] = []
    for col_pos in positions:
        row_styles = style_ready._from_row(data._tbl_data, col_pos.row)
        crnt_info = StyleInfo(
            locname=loc, colname=col_pos.colname, rownum=col_pos.row, styles=row_styles
        )
        all_info.append(crnt_info)
    return all_info

Here's the usage and result of the helper function.

import polars as pl

from great_tables import GT, from_column, loc, style
from gt_extras._utils_style import get_style_fill_info

df = pl.DataFrame({"col1": [1, 2], "color": ["red", "green"]})
gt = GT(df)

get_style_fill_info(gt, style.fill(from_column("color")))
#  or
get_style_fill_info(gt, style.fill(pl.col("color")))

[StyleInfo(locname=LocBody(columns='color', rows=None, mask=None), grpname=None, colname='color', rownum=0, colnum=None, styles=CellStyleFill(color='red')),
 StyleInfo(locname=LocBody(columns='color', rows=None, mask=None), grpname=None, colname='color', rownum=1, colnum=None, styles=CellStyleFill(color='green'))]

The information we need is rownum and styles.

I believe the result is sorted in ascending order of rownum, but for safety, we could explicitly apply sorted() with rownum as the key.

With these two pieces of information, we can pass the color value in the final loop of res = res.fmt() to the fill= or background= parameters.

[juleswg23]

Admittedly, I have some trouble following the logic of a code block without executing it 🤦‍♂️ so sorry in advance if this is a silly question – what happens if the cell already has a CellStyleFill style given by some other method?

Regardless, I am still on board with this kind of functionality, so feel free to proceed as you see fit.

[jrycw]

Apologies for not explaining this clearly earlier—I think we might have been slightly off the same page.

Using gt_plt_bar() as an example, imagine a column named "color" that holds color names as strings.

The use case I envision is combining style.fill() with from_column() (or a Polars expression) to assign colors based on this column, like so:

gt.pipe(
    gte.gt_plt_bar,
    columns=["hp", "hp_rpm", "trq", "trq_rpm", "mpg_c", "mpg_h"],
    show_labels=True,
    label_color=style.fill(from_column("color")),
)

The core idea is to extract the literal color strings (e.g., "red", "green") and apply them to parameters like fill=, background=, or here, label_color=, in the internal rendering functions.

The original cell styles for the columns and the color column would ideally stay unchanged with this approach.

Would gt-extras be interested in supporting this functionality? If so, I’ll try to prepare a draft PR.

[juleswg23]

Okay, I think I am understanding a little more.

To clarify, does this mean passing a color: label_color=style.fill("red"), is not supported? I would imagine this is this case because we already have that behavior by setting label_color="red".

If it only accepts a from_column() or pl.col() argument, then perhaps it could look like this?

gt.pipe(
    gte.gt_plt_bar,
    columns=["hp", "hp_rpm", "trq", "trq_rpm", "mpg_c", "mpg_h"],
    show_labels=True,
    label_color=from_column("color"), # or label_color=pl.col("color")
)

I don't know if this is harder to implement, but I think the style.fill might be a misnomer if I understand the application correctly.

[jrycw]

Thanks for pointing out that we can directly use from_column() without style.
I’ve prepared the draft code in #162.

We can use a string as input for label_color= as usual:

import pandas as pd
import polars as pl
import polars.selectors as cs
from great_tables import GT, from_column
from great_tables.data import gtcars

import gt_extras as gte

gtcars_mini_pd = gtcars.loc[9:17, ["model", "mfr", "year", "hp", "hp_rpm"]].assign(
    color=lambda df_: pd.Series(
        ["lightgreen"] * 4 + ["yellow"] * 4 + ["white"], index=df_.index
    )
)

gt = (
    GT(gtcars_mini_pd, rowname_col="model")
    .tab_stubhead(label="Car")
    .cols_align("center")
    .cols_align("left", columns="mfr")
    .cols_hide("color")
)

gt_pl = (
    GT(pl.from_pandas(gtcars_mini_pd), rowname_col="model")
    .tab_stubhead(label="Car")
    .cols_align("center")
    .cols_align("left", columns="mfr")
    .cols_hide("color")
)

gt.pipe(
    gte.gt_plt_bar,
    columns=["hp", "hp_rpm"],
    show_labels=True,
    label_color="lightgray",
)

Or use from_column():

gt.pipe(
    gte.gt_plt_bar,
    columns=["hp", "hp_rpm"],
    show_labels=True,
    label_color=from_column("color"),
)

Or use a callable:

gt.pipe(
    gte.gt_plt_bar,
    columns=["hp", "hp_rpm"],
    show_labels=True,
    label_color=lambda x: x["color"],
)

Or use pl.col():

gt_pl.pipe(
    gte.gt_plt_bar,
    columns=["hp", "hp_rpm"],
    show_labels=True,
    label_color=pl.col("color"),
)

Or use Polars selectors:

gt_pl.pipe(
    gte.gt_plt_bar,
    columns=["hp", "hp_rpm"],
    show_labels=True,
    label_color=cs.by_name("color"),
)

Interestingly, this conecpt can be injected into many parameters in gt-extras functions. However, there are two points to keep in mind:

1. The type hint will become complex (a new annotation may be needed, but I didn’t implement this in the draft).
2. The resolved values need to be bound in the final loop of res = res.fmt(). For formatting functions, the values should be bound using keyword arguments — I made this mistake earlier, and it took me a while to spot it.

By the way, style.fill() was not a good example in my previous demo. The most suitable example would be the color= attribute of style.text().

[juleswg23]

Ah, this is becoming very clear now! Thanks for the demo PR.

I had been picturing the purple bar was the color being modified, not the text. (Though I suppose it would not be difficult to apply this logic to the fill parameter as well.)

To your points,

1. The type hint will become complex (a new annotation may be needed, but I didn’t implement this in the draft).

This is definitely something to weigh. It may help that we can reference the GT docs, but on the other hand it definitely adds some complexity to a suite of plotting functions each with a lot of parameters already. Then again, I really don't love how haphazard the different plotting functions' parameters are, so maybe this is a step towards unifying them.

2. The resolved values need to be bound in the final loop of res = res.fmt(). For formatting functions, the values should be bound using keyword arguments — I made this mistake earlier, and it took me a while to spot it.

Yes! I struggled with this a ton when doing some of the earlier work, I'm glad to see you figured it out in the end.