The design philosophy of Great Tables

I'm a big fan of Tufte and he certainly informs a lot of my opinions on making tables and figures :)

The historical background about tabular displays of quantitative information is very interesting. I imagine it must have been fun think deeply about this problem.

Unfortunately, the API design in the example is just not very good:

    (
       GT(simple_table, rowname_col='Name')
      .tab_header(title='Names, Addresses, and Characteristics of Remote Correspondents')
      .tab_stubhead(label=md('*Name*'))
      ...
    )

I'm uncertain if it's trying to mimic something in another language like R (or some grammar of graphics thing or D3.js.) Hopefully, it's not trying to mimic the look of long, chained `pandas.DataFrame` operations (because it misses the point of why those look the way it does.)

Of course, for ad hoc, in-a-notebook, cut-and-paste/written-from-scratch use, the API design doesn't really matter that match. Usually, users will readily memorise the required incantations then fiddle with the result until they get what they want or they give up.

It's probably the case that for most tools that produce visual outputs, a majority of users are creating things in this style. (There are, e.g., millions of casual Matplotlib users out there.) But programmatic use is not too far off. Tools that produce visual outputs (even those as formally rigidly at display tables,) are often subject to consistency requirements, which directly implies programmatic use.

So, when I discover that my colleagues and I have six tables across three notebooks that need a consistent look, and I decide to interact with this tool programmatically, am I expected to write…?

    def standard_table(source, /, rowname_col, header_title, stubhead_label, weight_columns):
      return (
        GT(source, rowname_col=rowname_col)
        .tab_header(title=header_title)
        .tab_stubhead(label=md(f"*{stubhead_label}*"))
        .fmt_integer(columns=weight_columns, pattern="{x} lbs")
        ...
      )

    standard_table(simple_table, rowname_col='Name', header_title='Names, Addresses, and Characteristics of Remote Correspondents', stubhead_label='Name', weight_columns='Weight')

Or maybe…?

    def format_table(weight_columns):
      return (
        tbl
        .tab_stubhead(label=md(f"*{tbl.stubhead.label}*")) # what if not present?
        .fmt_integer(columns=weight_columns, pattern="{x} lbs")
        ...
      )

    format_table(
      GT(simple_table, rowname_col='Name')
      .tab_header(title='Names, Addresses, and Characteristics of Remote Correspondents')
      .tab_stubhead(label='Name')
      ...
    )

Or maybe…?

     class StandardTable(GT):
       def tab_stubhead(self, *a, **kw):
         # inspect.signature.bind(...) # ...
         return super().tab_stubhead(*a, **kw)

    StandardTable(...)

These aren't great options. The API design is just not very good.

I overall like the approach for complex scenarios but their example is not the best one. The original version is much more readable and their final version adds mostly noise.

Also, in documents all images and tables should have descriptive captions. So their header with title and subtitle would be redundant.

I Use SAS reports in my job pretty heavily I'm keen to find alternatives - this looks pretty promising.

One thing in particular I'm interested in but could not see an example for is if this will let you insert "break lines" i.e. for displaying sub totals and similar.

For example based on the demo, which shows names and addresses from census data it might be nice to be able to break at each change in postcode and display some summary data like a count of people found at that postcode or an average age (based on the DOB) living at that postcode or similar.

Otherwise conditional formatting is another pain point either using rules i.e. if value in column B is greater than a specified threshold make the entire row bold. Or automatically creating a color gradient to highlight the cells ala Excel.

For bonus points management types like things like red and green traffic lights (or down/up arrows) you can display next to kpi data in a table It's a gimmick but wins you points.

Me too. It‘s listed on eBay for $145 which is a lot of money.