Rich Iannone | What's new and exciting in gt 0.8.0 | Posit
With the gt package, anyone can make wonderful-looking tables using the R programming language. Rich Iannone, maintainer of gt, shows what's new and improved in gt 0.8.0! 00:00 Introduction 00:42 Find/Replace values with sub_values() 02:46 Find values and style them with tab_style_body() 05:00 Place a cell in your Quarto/RMarkdown doc with extract_cells() 07:13 Make numbers more readable with cols_align_decimal() 08:54 See column id info with tab_info() 11:03 Date and time formatting improvements For more details: • Demo script in this video: https://pos.it/gt8 • Read the blog post on gt 0.8.0: https://posit.co/blog/new-features-upgrades-in-gt-0-8-0/ • Learn more at https://gt.rstudio.com/ • See a full list of new features and improvements at https://gt.rstudio.com/news/index.html#gt-080
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
Hi, I'm Rich, I work at Posit, and formerly RStudio, and I work on the gt package, have been working on it for a while, and we have a great new release, 0.8, and today I'd like to show you what we improved in terms of new functions in the package, and also what we improved in terms of existing functions in the package.
We added a bunch of great new functions to target values and do cool things like replace the values of the things that were targeted, or style the cells. And the other thing is improvements to date and time formatting especially. So I'm really excited to talk about these new features, let's dive right in.
Find/replace values with sub_values()
So the first function I want to talk about is sub underscore values, or sub values. So it's essentially like a find and replace. So we have a table here, I just made that with the table function from dplyr, I'm showing you the table now in the console, and we can look at the table as it is in gt just by piping it to the gt function. So this is the table just down here, formatted as html.
So we can use sub values, I'm using it three times here, but I'll show you each time I use it that we can find and replace values. So in the first case I'm looking for values like 74 and 500, and replacing with 150. So if I run this, this is going to change very subtly, but you'll see 150 is there now.
If we do the same thing with finding the letter B, and replacing with the word B, that works. It'll just skip over these numeric columns and go right to the thing that is a character column. And same thing with 800, you can replace any text, so it could be any size text, replacing the value 800 with the words 800 right here. So that's sub values.
You can do quite a bit with it, you can even have patterns. If you know about regex, you'll know what this is, essentially it could be A or C or E. If you find any of those, you can replace the whole cell with A's. So let's run this. You can see right here that these values right here are replaced with that replacement value.
So we can do more advanced things. Use a function that you supply, for instance. So this is going to be values that are less than 50, and the text you're going to replace those values with is under 50. So let's just run this and take a look at the result. There we are. Lots of values which are under 50 in this column, and also in the first column. It totally ignores the column which doesn't have numerical values at all, which is kind of nice. You don't have to specify which columns, it won't error on you or do weird things.
Styling cells with tab_style_body()
I want to talk about another function which is new in GT 0.8. It is tab style body. Okay, so let's start with a initial table right here. This is just like an example table that I use a lot in GT for examples. And what we can do now is we could do a similar sort of thing. We can find values and then style the cells that have those values. So these are literal values, 49, 95 and 33, 33, they exist over here. So let's actually run this and see what the result is. Okay, so we got some values which are colored in orange. That's because we have the style here set with this helper function called cell underscore fill and the color of orange. So we're essentially filling those targeted cells with that styling.
So we can do lots more with this, we can have multiple styles. You just enclose them in a list, we can style the text, we can style the fill of those cells that we target, we can even style the borders of those. So we're doing the same thing, targeting the same values. So if I run this, you'll see that the only thing that changes is in those two cells, the styling will totally change. There you go. So it's totally different styling, but targeting the same cells with these literal values. So that's tab style body.
There's more to it. You can have sub values that I spoke about earlier, and you can have different types of targets. You can target row and target column. What does that do? It just means that if it finds anything, like a cell, it'll just style the entire row or the entire column. So let's actually take a look at that. So let's do this whole statement, run it, and see here that because it found 49.95 over here, and we said targets equals row, it's going to style it with cell fill color of light green all the way across.
So it's a good way of highlighting a row, just based on data you have, you want to highlight a row. You can do the same thing with this statement right here, column. So it found this value, it's a little hard to read, but that's 33.33. Because we have targets equals column, we're styling the entire column. So that's what that does.
Placing cells in documents with extract_cells()
I'm going to skip ahead here and move to another new function we have in GT 0.8. It's extract cells. So what it does is it allows you to pull out certain cells from a GT table. So you have a GT table, but you just want like a value from that table and you want to put it somewhere. You can do that with this function here. So it's actually best shown in a Quarto document. I have one open right here.
So what I'm doing is I'm making a giant table here. And the key to this is I have a table, I saved it as such, like I assigned it to this object and displaying it, but I have it assigned as an object. That's a key thing here. So what you can do in Quarto and in R Markdown is you can use inline R code. It's basically this backtick with an R and some code inside there and closing with a backtick.
So that's kind of cool because we can actually take that GT table, pipe it into extract cells, pull out the cell we want. And the interesting thing about this is that cell is already fully formatted. So you'll get the same formatting in the text of your document. It's a little hard to imagine that right now because we just have the source document. So let's actually render it. Going to hit the render button and then it's going to do its thing in that background jobs window. And when it's done, it should appear as a preview.
And the key thing is we'll see in this last paragraph that we'll have a value from the table. Okay, great. So I'm going to expand this a little bit, move to the bottom. So I kept the code in here. The table should be below. Great. So I pull out a value, which is one of these fractions. It's a little bit harder to format in HTML. You have to do a little bit of like tag stuff. But we don't have to worry about that because we have extract cells and we pulled out the cell, which is from column F underscore sold and row number 14. And it's right here, 2 over 10.
So kind of nice. You didn't have to replicate that. You can use something you already have inside your document. And it saves a lot of transcription problems in the future. And if this table changes, this changes accordingly, which is really cool. So that's extract cells.
And if this table changes, this changes accordingly, which is really cool.
Decimal alignment with cols_align_decimal()
We have another new function in GT 0.8, and it is the one called cols align decimal. So this is like an often requested bit of functionality. So we have a table here, for instance. Let's run this. So we're just generating a table. It's a really simple table just for demonstration purposes. And say we want to format this entire column of numbers. We want three decimal places. We want drop any trailing zeros. And that's, you know, that's pretty much it for that column. So let's actually run that little bit right there.
Okay, this is great. The problem is that it's a little hard to read because the decimals aren't lined up in a way that, you know, makes it easy to see what is, you know, before and after the decimal mark. And there's not always a decimal mark here. This is like a whole number with no decimal. So a little hard to read. You know, it's not impossible, but it's not, you know, it can be better. So that's where this function comes in, cols align decimal. You just run that. You can target a column, but you don't have to. It just runs across the entire table, looks for columns that have numbers formatted, and just does the thing.
So let's actually run this. Great. Okay, so an immediate improvement. So basically what we have now is we have the decimal running all the way down. I mean, this is like a sort of extreme example. We have NAs and sort of some wild values here. But the idea is that it's a little easier to read, especially if you, you know, just have a ton of these values. You just want to see what the big part is and what the small part of the number is. So that's cols align decimal, just decimal alignment.
Inspecting column IDs with tab_info()
So next is information about your table. You might make a really complex table like this. You know, if you're a beginner with GT, you might not know what this is. That's fine. That's actually, that's actually just fine. So let's run this. Let's show the table. So it's a pretty nice looking table. We have, you know, row labels here and we have column labels across the top and a spanner that spans across two columns and some formatted values in the body.
Yeah, you might get this table or you might want to style something like, say, for instance, you know, this column or some cell in there, right? So we don't know how to do that because we need to do is you have to know the ID value of, you know, like the column and also of the row. So to help that, we have this new function called tab underscore info or tab info for short. You just pass that your GT table. And what you get is an information table that shows you what your columns are called in terms of IDs and then what the labels are.
So you can sort of see what you have currently in your viewer in terms of what you have in your table and you make the correspondence between that and your actual like ID, which is used for styling and for things like footnotes. So we have that even the rows might be labeled differently than their ID values. And it also works for spanners as well. So wherever you have in your table, this will reveal what the ID values are. And this is important because sometimes with certain functions in GT, it just creates IDs for you and you have no idea what they are. So this gives them to you so you can do styling.
So if you go back to your other table here, we want to style, say, for instance, this column right here. And, you know, we didn't know what this was called. For instance, we know it's actually MPGG underscore C from this table here. That's what it appears to be. And that's what it is. So now if we run this, we can successfully style that entire column with a background color of light blue. Because if we just put an MPG like this, we would just get an error.
Date and time formatting improvements
The next function I want to talk about, actually it's a set of functions, have to do with the date and time formatting features in GT. We have a number of functions, format date, format time, format daytime. Those have completely been overhauled, rewritten, totally feature packed now, lots more power than before. And we hope it's actually even easier to use than before. So let's get right to it.
So let's start with a date time string. So we can actually format that with this other function. It's a variant of format date, vec format date. So it's great for examples and it's great for anything inside, you know, R Markdown or Quarto if you just need formatted values like from vectors and not from columns of values in a table. It's also good for demonstration purposes. So it has all the same features. It just works on vectors rather than columns in a table.
So if we were to take our date string, what we could do is we could use a date style. And these are name styles that are available in this function and also in this function. It just allows easy access to like styling, you know, an input date time to whatever output date time. So we do the same thing for formatting times. So we're just getting the time portion of this out. In this case, we're getting 10.05 p.m. because that's what that is here in the string.
So it's all very overwhelming. Like, where do we get these? You know, there's lots of them. We actually have a function in GT called info date style. We can just run that. And what it does is it gives us a table of all the different format names that you can use here in date style. And it gives you an example with an input. And so you just look down and see what, you know, the different outputs are for the same date. So really kind of cool. You just got to copy and paste this, put it into here and you're off essentially.
So same sort of thing for the time styles because it's a separate function. It's got a separate function for the info table right here. Great. So you see HMP is this right here. And this is the example formatted time. So that's all great. We also have this other function called format date time. It has tons of power. It allows you to actually use a formatting string and to style your date time strings just the way you want them. So we can use date styles and we can use time styles together. And it will separately format those two parts and give you an output. So let's actually see it in practice. So we get this. We get the date and then we get the time just after that.
Okay. A cool new thing that was added in the latest release is that you can have locales. So say for instance, you want a time in a different language. So you can use the same input. You just have to use locale and then the name of the locale and you will get the output date in that language, like basically specific for that locale. So that's a new thing.
So another new thing is we have a totally different way of formatting dates and times with this new type of format string. You can still use the old type that hasn't changed, but it will detect whether using this other type, which is called CLDR. So it basically has more fields for formatting dates and times. It's way more flexible. It has tons of support for time zones as well if you have that in your input, which is totally supported here. But I just want to say that this is a great way of formatting really advanced dates and times. So that's one example here. And it's fully localizable. So we can just put the locale here and it just switches it to the Dutch version of that date time, which is really cool.
So we can just put the locale here and it just switches it to the Dutch version of that date time, which is really cool.
So learning about this is actually kind of difficult. It's almost like you need a crash course in this whole thing. But that's no problem because we actually have documentation and it's really extensive in the project website for GT. And it's available at gt.rstudio.com and particularly look at the reference section and you'll find that the daytime formatting functions and the documentation is super huge and there's tons of help on all this stuff.
So that's all I have for the new enhancements and features in GT. This is a great script. It allows you to sort of like test out things that are new and we'll have this script available for everybody to use and the link to it will be available in the video notes. If you have any questions about GT, you can always ask me in the issues in GT, which is at the GitHub repository for the package. If you want to have a reference for GT, you can go to gt.rstudio.com. There's a full reference there, lots of articles and lots of reference materials for you to learn how to use the package.
