cols_width() method now makes this possible.
Here's an example where the widths of all columns are set with our preferred length values (in `px`).
``` python
import warnings
from great_tables import GT, exibble
warnings.filterwarnings("ignore")
exibble_mini = exibble[["num", "char", "date", "datetime", "row"]].head(5)
(
GT(exibble_mini).cols_width(
cases={
"num": "30px",
"char": "100px",
"date": "150px",
"datetime": "200px",
"row": "50px"
}
)
)
```
| num | char | date | datetime | row |
|--------|---------|------------|------------------|-------|
| 0.1111 | apricot | 2015-01-15 | 2018-01-01 02:22 | row_1 |
| 2.222 | banana | 2015-02-15 | 2018-02-02 14:33 | row_2 |
| 33.33 | coconut | 2015-03-15 | 2018-03-03 03:44 | row_3 |
| 444.4 | durian | 2015-04-15 | 2018-04-04 15:55 | row_4 |
| 5550.0 | | 2015-05-15 | 2018-05-05 04:00 | row_5 |
You don't have to define widths for all columns with cols_width(), and you're free to use either `px` or `%` values when defining widths. See the [reference page](../../reference/GT.cols_width.md#great_tables.GT.cols_width) for more information and relevant examples.
## Setting options across the entire table with [tab_options()](../../reference/GT.tab_options.md#great_tables.GT.tab_options)
The new tab_options() method gives you the freedom to specify any of dozens of global style and layout options for the table. Want a font that's used across all cells? Use the `table_font_names=` option. Do you need to make the text smaller, but only in the stub? Use `stub_font_size=` for that. The number of options is perhaps overwhelming at first but we think you'll enjoy having them around nonetheless. It makes styling the table (and developing your own table themes) a relatively simple task.
Here's an example that creates a table with a few common components and then uses tab_options() to set up a collection of fonts for the table with the (also new) system_fonts() function:
``` python
from great_tables import md, system_fonts
gt_tbl = (
GT(
exibble[["num", "char", "currency", "row", "group"]],
rowname_col="row",
groupname_col="group",
)
.tab_header(
title=md("Data listing from **exibble**"),
subtitle=md("`exibble` is a **Great Tables** dataset."),
)
.fmt_number(columns="num")
.fmt_currency(columns="currency")
.tab_source_note(source_note="This is only a subset of the dataset.")
)
gt_tbl.tab_options(table_font_names=system_fonts(name="industrial"))
```
| Data listing from exibble | |||
|---|---|---|---|
| [exibble](../../reference/data.exibble.md#great_tables.data.exibble) is a Great Tables dataset. | |||
| num | char | currency | |
| grp_a | |||
| row_1 | 0.11 | apricot | $49.95 |
| row_2 | 2.22 | banana | $17.95 |
| row_3 | 33.33 | coconut | $1.39 |
| row_4 | 444.40 | durian | $65,100.00 |
| grp_b | |||
| row_5 | 5,550.00 | $1,325.81 | |
| row_6 | fig | $13.26 | |
| row_7 | 777,000.00 | grapefruit | |
| row_8 | 8,880,000.00 | honeydew | $0.44 |
| This is only a subset of the dataset. | |||
system_fonts() helper function in **Great Tables** makes this easy by providing you with themed, local font stacks that are meant to work across different computing platforms.
Here's another example where we set the width of the table to span across the entire page (or containing element).
``` python
gt_tbl.tab_options(table_width="100%")
```
| Data listing from exibble | |||
|---|---|---|---|
| [exibble](../../reference/data.exibble.md#great_tables.data.exibble) is a Great Tables dataset. | |||
| num | char | currency | |
| grp_a | |||
| row_1 | 0.11 | apricot | $49.95 |
| row_2 | 2.22 | banana | $17.95 |
| row_3 | 33.33 | coconut | $1.39 |
| row_4 | 444.40 | durian | $65,100.00 |
| grp_b | |||
| row_5 | 5,550.00 | $1,325.81 | |
| row_6 | fig | $13.26 | |
| row_7 | 777,000.00 | grapefruit | |
| row_8 | 8,880,000.00 | honeydew | $0.44 |
| This is only a subset of the dataset. | |||
| Data listing from exibble | |||
|---|---|---|---|
| [exibble](../../reference/data.exibble.md#great_tables.data.exibble) is a Great Tables dataset. | |||
| num | char | currency | |
| grp_a | |||
| row_1 | 0.11 | apricot | $49.95 |
| row_2 | 2.22 | banana | $17.95 |
| row_3 | 33.33 | coconut | $1.39 |
| row_4 | 444.40 | durian | $65,100.00 |
| grp_b | |||
| row_5 | 5,550.00 | $1,325.81 | |
| row_6 | fig | $13.26 | |
| row_7 | 777,000.00 | grapefruit | |
| row_8 | 8,880,000.00 | honeydew | $0.44 |
| This is only a subset of the dataset. | |||
tab_options(), so have a look at its [reference page](../../reference/GT.tab_options.md#great_tables.GT.tab_options) for more information and useful examples.
## Using the new `opt_*()` methods to do more complex tasks with table options
While tab_options() is a great method for setting global table options, sometimes you want to set a number of them at once for a combined effect. For that type of operation, we have the `opt_*()` series of methods. A common thing you might do is align the content in the table header, we can make that an easy thing with opt_align_table_header():
``` python
gt_tbl.opt_align_table_header(align="left")
```
| Data listing from exibble | |||
|---|---|---|---|
| [exibble](../../reference/data.exibble.md#great_tables.data.exibble) is a Great Tables dataset. | |||
| num | char | currency | |
| grp_a | |||
| row_1 | 0.11 | apricot | $49.95 |
| row_2 | 2.22 | banana | $17.95 |
| row_3 | 33.33 | coconut | $1.39 |
| row_4 | 444.40 | durian | $65,100.00 |
| grp_b | |||
| row_5 | 5,550.00 | $1,325.81 | |
| row_6 | fig | $13.26 | |
| row_7 | 777,000.00 | grapefruit | |
| row_8 | 8,880,000.00 | honeydew | $0.44 |
| This is only a subset of the dataset. | |||
tab_options() to find the two args you need to get the job done.
The opt_all_caps() method transforms the text within the column labels, the stub, and in all row groups so that we get an all-capitalized (yet somewhat sized down) look that better differentiates the labels from the data. It's rather easy to use, just do this:
``` python
gt_tbl.opt_all_caps()
```
| Data listing from exibble | |||
|---|---|---|---|
| [exibble](../../reference/data.exibble.md#great_tables.data.exibble) is a Great Tables dataset. | |||
| num | char | currency | |
| grp_a | |||
| row_1 | 0.11 | apricot | $49.95 |
| row_2 | 2.22 | banana | $17.95 |
| row_3 | 33.33 | coconut | $1.39 |
| row_4 | 444.40 | durian | $65,100.00 |
| grp_b | |||
| row_5 | 5,550.00 | $1,325.81 | |
| row_6 | fig | $13.26 | |
| row_7 | 777,000.00 | grapefruit | |
| row_8 | 8,880,000.00 | honeydew | $0.44 |
| This is only a subset of the dataset. | |||
tab_options() all at once, making life generally easier.
Here's one last example, this time using opt_vertical_padding(). You'd use that if you're dissatisfied with the level of top/bottom padding within cells of all locations (e.g., in the table body, in the column labels, etc.). You can either make a table taller or more 'compressed' with a single argument: `scale=`. Here's an example where the amount of vertical padding is reduced, resulting in a table taking up less vertical space.
``` python
gt_tbl.opt_vertical_padding(scale=0.5)
```
| Data listing from exibble | |||
|---|---|---|---|
| [exibble](../../reference/data.exibble.md#great_tables.data.exibble) is a Great Tables dataset. | |||
| num | char | currency | |
| grp_a | |||
| row_1 | 0.11 | apricot | $49.95 |
| row_2 | 2.22 | banana | $17.95 |
| row_3 | 33.33 | coconut | $1.39 |
| row_4 | 444.40 | durian | $65,100.00 |
| grp_b | |||
| row_5 | 5,550.00 | $1,325.81 | |
| row_6 | fig | $13.26 | |
| row_7 | 777,000.00 | grapefruit | |
| row_8 | 8,880,000.00 | honeydew | $0.44 |
| This is only a subset of the dataset. | |||
opt_align_table_header()
- opt_all_caps()
- opt_vertical_padding()
- opt_horizontal_padding()
and we plan to add more `opt_*()` methods in future releases.
## A new formatting method: [fmt_image()](../../reference/GT.fmt_image.md#great_tables.GT.fmt_image)
Wouldn't it be great to add graphics to your table? The fmt_image() method provides an easy way to add image files on disk into table body cells. The cells need to contain some reference to an image file. The `path=` and `file_pattern=` arguments give you some flexibility in defining exactly where the image files live.
Here's an example using the [metro](../../reference/data.metro.md#great_tables.data.metro) dataset that's included within **Great Tables**.
``` python
from great_tables.data import metro
from importlib_resources import files
img_paths = files("great_tables") / "data/metro_images"
metro_mini = metro[["name", "lines", "passengers"]].head(5)
(
GT(metro_mini)
.fmt_image(columns="lines", path=img_paths, file_pattern="metro_{}.svg")
.fmt_integer(columns="passengers")
.cols_label(
name="Station",
lines="Metro Lines",
passengers="Passengers per Year (2021)"
)
.tab_options(table_width="700px")
)
```
| Station | Metro Lines | Passengers per Year (2021) |
|----|----|----|
| Argentine | | 2,079,212 |
| Bastille | 
| 8,069,243 |
| Bérault | | 2,106,827 |
| Champs-Élysées--Clemenceau | 
| 1,909,005 |
| Charles de Gaulle--Étoile | 
| 4,291,663 |
Notice that `path=img_paths` specified the folder the images live in, and `file_pattern="metro_{}.svg"` provided a template for converting each value in the `lines` column to an SVG file name.
The fmt_image() method supports three kinds of files as inputs, either: (1) complete http/https or local paths to the files; (2) the file names, where a common path can be provided via the `path=` arg; or (3) a fragment of the file name, as shown in the example above.
The package has some graphics stored in the `data/metro_images` directory. They are SVGs and they look *very* nice in the example table!
See the fmt_image() reference page for more information on this new method.
## Wrapping up
This `v0.3.0` release has some great new methods that add value to most any table-making endeavor. We also fixed a few bugs along the way so that you'll have a overall smoother experience when building beautiful tables. As ever, we'll work toward more and more improvements to give you more creative possibilities!