GT.fmt_time(self, columns=None, rows=None, time_style='iso', pattern='{x}', locale=None)
Format values as times.
Format input values to time values using one of 5 preset time styles. Input can be in the form of time values, or strings in the ISO 8601 forms of HH:MM:SS or YYYY-MM-DD HH:MM:SS.
| Name | Type | Description | Default |
|---|---|---|---|
columns |
SelectExpr |
The columns to target. Can either be a single column name or a series of column names provided in a list. | None |
rows |
int | list[int] | None |
In conjunction with columns=, we can specify which of their rows should undergo formatting. The default is all rows, resulting in all rows in targeted columns being formatted. Alternatively, we can supply a list of row indices. |
None |
time_style |
TimeStyle |
The time style to use. By default this is the short name "iso" which corresponds to how times are formatted within ISO 8601 datetime values. There are 5 time styles in total and their short names can be viewed using info_time_style(). |
'iso' |
pattern |
str |
A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the {x} (which can be used multiple times, if needed) and all other characters will be interpreted as string literals. |
'{x}' |
locale |
str | None |
An optional locale identifier that can be used for formatting values according the locale’s rules. Examples include "en" for English (United States) and "fr" for French (France). |
None |
Time_Style ArgumentWe need to supply a preset time style to the time_style argument. The time styles are numerous and can handle localization to any supported locale. The following table provides a listing of all time styles and their output values (corresponding to an input time of 14:35:00).
| Time Style | Output | Notes | |
|---|---|---|---|
| 1 | "iso" |
"14:35:00" |
ISO 8601, 24h |
| 2 | "iso-short" |
"14:35" |
ISO 8601, 24h |
| 3 | "h_m_s_p" |
"2:35:00 PM" |
12h |
| 4 | "h_m_p" |
"2:35 PM" |
12h |
| 5 | "h_p" |
"2 PM" |
12h |
We can use the info_time_style() function within the console to view a similar table of time styles with example output.
| Type | Description |
|---|---|
| GT | The GT object is returned. This is the same object that the method is called on so that we can facilitate method chaining. |
LocaleThis formatting method can adapt outputs according to a provided locale value. Examples include "en" for English (United States) and "fr" for French (France). Note that a locale value provided here will override any global locale setting performed in GT()’s own locale argument (it is settable there as a value received by all other methods that have a locale argument).
Let’s use the exibble dataset to create a simple, two-column table (keeping only the date and time columns). With the fmt_time() method, we’ll format the time column to display times formatted with the "h_m_s_p" time style.
from great_tables import GT, exibble
exibble_mini = exibble[["date", "time"]]
(
GT(exibble_mini)
.fmt_time(columns="time", time_style="h_m_s_p")
)| date | time |
|---|---|
| 2015-01-15 | 1:35:00 PM |
| 2015-02-15 | 2:40:00 PM |
| 2015-03-15 | 3:45:00 PM |
| 2015-04-15 | 4:50:00 PM |
| 2015-05-15 | 5:55:00 PM |
| 2015-06-15 | |
| 7:10:00 PM | |
| 2015-08-15 | 8:20:00 PM |
The functional version of this method, val_fmt_time(), allows you to format a single numerical value (or a list of them).