RMarkdown Parameterized Reports Will Save You HOURS of Work

so knit with parameters and we get this so in this case you can actually change what year you want it set to you get a drop down of all of your selectable options that are available to you if you want to select a file it'll open up your file system that's really useful if you're going to [Music] welcome back everyone my name is brian jenks and today we're going to talk about parameterized our markdown reports what they are and why you should care let's say you have a report you have to run it for 35 different people or businesses or you know a variety of other variables that are all changing but you just need to change just those variables and otherwise your report is basically the same kind of like a cookie cutter template but where you change out some of those critical pieces so that the information contained within it is different well if you want to have only one document and just change in some input parameters to that document and have basically a one-stop shop template for doing this report for all these varieties of scenarios this is a type of workflow tool for you most of this is really just messing with yaml headers in the are marked on documents some of the pre-built options in our studio and a little bit with shiny but it's going to be pretty basic and you're going to see some of the power of this so let's just jump right into rstudio so right off the bat first thing we always do i'm on mac so it's command shift f10 but we're going to start a brand new r session we want a brand new clean slate just in case so with that done what are we going to do so with parameterize our markdown it's mostly contained in the yaml front matter so yaml is that little section up at the top of a new arm our markdown document so we can start a new document you can see what it looks like you know up here at the top this is your yaml header it is an interesting type of syntax where you just have colon separated values a little bit like json without all the braces and what this is going to do is help us get some meta options for our document so i've popped over into a strip down document just so you can see the bare bones functionality of using parameters so up in the ammo header at the top level you can see there's nothing to the to the left with yaml the indentation and the levels of indentation is very important so the first level we have output date author title these are all first level options also at the first level is something called params and then a colon to specify multiple items underneath one of these top level yaml items you have to take it to the next level and indent it so with that i now have another actual parameter so under params we have one which is youtube and the value for youtube is hello youtube so we can put these parameters in a variety of locations uh we'll see later how you can actually use it in the options for the r code chunks and this can come in very handy for an example i'll give later we can actually put it in a code chunk as like executable code so to access these parameters as like a variable like you'd normally use variables in code you just say params the dollar sign to like subset so your parameters you have if you had multiple so let's just say data as a parameter we could say i don't know test so let's say we have params we do a dollar sign to subset now you can see your two parameters that are defined in the yaml we just care about youtube so we can get rid of that one so with that we can actually have executable code and get output we could also use the inline r code in the markdown space for text and actually have it printed out as plain text as well this is something very useful if you're not only using it to execute code say is picking a data set but you also want to name what data set later on in your text just as plain text so with that we have it defined in codespace and markdown space let's knit and run and the output will look like this this is your code space you can see we executed params youtube and it actually has that output and also in the text itself very simplistic example of where you can actually place these and use them it can work in code it can work in text so let's go start looking at the more meaty examples so on this additional file we have a couple parameters already defined i have one for data a toggle parameter and a year cool also in comments i specified like our options here we're going to have two options mpg data set or diamonds data set and then true and false most of this document is commented out at the moment so i can show the examples incrementally but if we just run it right now let's see what kind of output we get so we get some junk here we don't care about but the mpg data set we defined mpg as a parameter and it was chosen in 2020 that's the year parameter and then the toggle one doesn't appear here because we actually have commented out all the other code but i'll show you where that comes in handy later and for instance there are some ideas what we can do with parameters i'll go over those in a minute and some useful resources i'll leave for you guys so let us uncomment some of this and see what we get so i have some code here i'm going to uncomment it it's just two very simple plots one is with mpg one is with diamonds and it's basically a simple tile and a bar plot not really snazzy or important but in the code chunk options you can see i have viz and viz2 here this has the option of include which is saying hey should i even include this code run it execute it do anything with it the option of that is set to toggle now toggle was a binary true or false so do we want to include the code for toggle or not and for instance in this one i have an exclamation point so that this way whatever toggle is it'll be opposite for this one so when i have these two examples i'm just trying to show how you can also invert the parameter to get a result so in this case by setting toggle to something one of these charts is not going to be displayed so just by uncommenting the code with mpg as our data set true for our toggle and the year as 2020 we're going to knit again and our output looks pretty similar except now we actually have the mpg data set because toggle was set to true so we have mpg 2020 mpg the whole toggle uh chart is now displayed here great so with parameters we can also selectively choose which code chunks we actually want to con like use execute and retain in our document documents final output let's see what happens when we change it to the diamonds data set so i'm going to change this to diamonds and with diamonds because it was set to true for the mpg code chunk we're going to set it to false which is just this example you don't have to do this and then we change the year to 2018. so now if i knit that with those new options we're going to see that now the diamonds data set in 2018 now displays the code chunk for diamonds so you can see how with parameters we can selectively choose which parts of information and code we want to show and execute but we can also change what is being used as a variable so for instance if this diamonds right here and i only had one code chunk and the j the general uh char chart plot thing was uh simple enough and like a template we could easily just change hey which data set are we plopping in here you know that's an option or you could easily change it to a specific variable for a large group of i don't know students names or something very very large amount of use cases for this now i know some of you are already going to notice something that could actually be you know this is a this is beneficial but there's still some level of manual work going on that's true one thing you can do programmatically is use some of the functions from the per package where you actually have basically like loops but in this case like mapping functions where you put in a vector of parameters to a single parameter so in this case we could say mpg diamonds and empty cars flights whatever those different data sets and then put all of those into the data parameter incrementally run the report and get an outputted report in this case you're generating four reports from a single function call and you don't have to manually change those values this type of thing i don't have an example for that made but one way you could do that is with this type of code right here where we're actually calling the our markdown render function we're passing it the name of the document and then i have params and we're giving it the list of parameters so in this case this is when you actually have the code of what you're going to execute and run and in this case what you're going to pass in as the parameters now it's it's code so you can easily pass in those parameters in you know map functions if you use this trick however you can't run it from a code chunk within this document or if you can i haven't figured out how to do it because i kept trying to get this to run like this and i kept getting errors so what i had to do was at first copy and comment this out save it and then within the console so if you could you could run this from an r script or another r markdown document but from within the console in my current working directory um actually not the console and a terminal so i'm in my current working directory i have my files in here uh there's the param.rmd and so what i'm going to do is i'm going to say r now i'm running r in the command line and then i'm just going to paste that function all this stuff our markdown render and all the parameters if i run that it will knit my document exactly as if we just hit knit and it will produce the output now it doesn't just open up the output like when we hit knit so i can actually go here go to the refresh go to param html and i can open in a web browser it will open up in my web browser and you can see that it is mpg 2019 wait a minute diamonds 2018 so what happens when we actually run this function is that it will override the existing parameters hard set in the files yaml header but if those fi of those parameters already exist and we don't explicitly override them they will still be used by as their defaults so in this case what we have is mpg 2019 and the toggle was set to true instead of false which is why we have this output so with that very useful function if you're going to overload the parameters and overwrite them and with a simple loop or map function this becomes a very useful trick for generating a mass of reports all in one template in the same vein as the prior render trick we can also pass the params argument the value ask what this does is it will actually open up a shiny interface to override your parameters or define them within your browser or your local host so in this case we can actually run this one from within our document and it will affect our output and we don't actually need to use this within the command line or the terminal so when i run this code currently you can see that i have diamonds false 2018 so when i run this and it opens up the shiny interface in my browser it's diamonds toggle is false and 2018. so let's change this to mpg let's turn toggle to true and let's change the year to 2021 and save right here at the bottom right and see what the output is so it doesn't disappear it doesn't close but it's grayed now if i return back to our studio it's you know there's some operations going on here some stuff happened so this actually does in fact produce your output document so when i open up param html which is this is param rmd so it's going to open up this document we have the mpg data set is now produced mpg 2021 and this has been toggled to true so that's why we see the mpg chart here so this is a pretty useful tool that you get a more graphical interface to actually manipulate your variables but it's kind of flat i mean you you saw that it says like you know your data here it doesn't give you any options toggle's just a checkbox and you know this doesn't really give us a lot of information what are the possibilities what can i do with this interface so that's one of the downsides of doing it with just the ask function or the ask parameter being passed there what we actually can do that's really really useful is we can actually knit with parameters so what does knitting with parameters actually look like so let me comment this out now with all that code commented out it's just going to be diamonds false 2018 but when i use the the knit button it'll just make the document but if i do knit options here a little drop down and knit with parameters it's going to open up that same shiny interface but not in my browser localhost it's going to open it from our mark our studio and now i have access to diamonds toggle 2018. cool 2018 actually comes with this little you know incrementer here that's cool we're going to change it to 2022 and yeah leave it at diamonds so now we can knit the document it's going to do that and then once it's finished because it's still in our studio it'll actually open up automatically unlike running the ask value for parameters and we can see 2022 diamonds it overloaded that yaml option for the parameter year and we have that output so knitting with parameters really cool to get a nice interface have it close when you're done and have it open up automatically like you're probably used to with rstudio so passing in params equals ask you know it's probably a little bit more work than just knitting with parameters but if you're using it outside of rstudio that's probably where you're going to get a better use case for that option so because that parameter interface is opening and basically is a small little shiny dashboard in a way we can do some cool things with that so i have a bunch of stuff here commented out but what we can do is with yaml we can actually specify a lot of options to pass to that shiny interface to make it more interactive and useful to us i'm going to copy out all or comment out all of those and uncomment all of these and so what do we get so for year now we have label value input is a slider we have a range we have you know uh incrementing steps by one separator is nothing now for data instead of just mpg or diamonds we actually have you know an input a select input of an array here so this is actually how you specify arrays in yaml so we can specify an array of options and then for file this is just some a bell and whistle i didn't actually need this or use this at all but you'll see what this looks like so if i just knit the document it's still going to say you know the defaults year is equal to 2017 right now unless we change it it's equal to mpg unless we change it and it's equal to that file you know that doesn't matter and then actually we're going to put toggle in here so because we forgot about that one so toggle is equal to true so with all those set let's knit with parameters again now this if you if you ran with params equals ask it'll do the exact same thing that i'm about to show you but it will open up in your browser it's just more efficient to do knit with parameters if you're using rstudio because then it pops up that window closes it when you're done and opens up your output for you automatically like you're used to unless you disable that option so knit with parameters and we get this so in this case you can actually change what year you want it set to you get a drop down of all of your selectable options that are available to you if you want to select a file it'll open up your file system that's really useful if you're going to take an input data set for some reason or you have a standard input that you can just put into here really useful feature toggle is still the same here but you get the idea there are a lot of options that you can do with this shiny interface and there's a link in the materials for this video that will be in the our markdown document below and i will put the link to it in the description or in the pin comment below so you can find all that there but a lot of options that we can actually do with this so with our defaults let's set it to 2013 uh mpg and for that toggle has to be true if we knit you'll get the exact same output that we've been seeing because it's still using those same parameters but once it's finished you're going to see the mpg toggle data set it's set to true mpg 2013. everything is exactly the same just with a nice interface to actually select your options and parameters so when might you find this to be a very useful tool i mean i think you can already start to see like how this can be implemented to make it more useful to you some examples i've seen and some ideas i've had about this are say say you're in education and you're teaching students if you want to give them some files and just have a you know your answer key easily hidden or presented or whatever you can actually use the like the toggle option or some other variable and toggle the answer sections for homework questions in this document because you can knit this our markdown document to a markdown document so if you give out homework in markdown or something like that you can see how you can withhold pieces of information so in this case your answer key and then you can deal with that so you have your answer key available to you you can hide it or whatever all one document answers and all send your students what they actually need to use and keep the answers to yourself uh you could also say you're going to make a report for all of your students so your 80 individuals in your company or whatever you have a data frame of all the details of those people and then you assign each of those details to a parameter you run a loop or a map function and then you generate a report for each of these people using the parameters that are each of the values for each observation in that data frame and then using the blastula package which is how you can send emails from r use the the knitted document and send that report through blastula and now you've just emailed everybody their compiled report based on a single button click basically you can you run all those functions generate all the reports attach them email them all within our and then the lastly uh example i gave here is say like you have different reports for regions or conditions of data so if you have um you know say you're doing something where you have to deal with each county in a state then you could easily run a report for each county and making everything simpler with one document a parameter input and all of the output documents are changed based on that conditional input very very useful tool for getting more work done with less ever effort thinking working smarter not harder there is a link that i will put this in the description below um i don't really have a place to put this document for a repo like my r package reviews but i will put this link in the comments for or then in the pin comment below the video because i thought it was a really great guide to doing some of the stuff with parameters it's ua's book down online book really useful resource for a lot of other things but really great examples of how to use these parameterized reports i will leave that in the comment section below so i hope you found that video interesting and useful if you like that type of content i have a whole playlist on just our markdown tips as well as full package reviews on my channel feel free to check those out and before i go thank you to my patrons devin alberto and klaus thank you guys for supporting the channel and i'll catch you guys in the next one [Music] you

Channel: Bryan Jenks

Views: 5,529

Rating: 4.9819002 out of 5

Keywords: software, code, coding, programming, software engingeering, r programming, rstats, data science, rmarkdown, r markdown, neovim, bryan jenks, macbook pro 16, new macbook pro, macbook pro, catalina, parameters, parameterized reports, rmarkdown parameters, how do i use parameters in rmarkdown, how do i put parameters in rmarkdown, how do i make parameterized rmarkdown reports, rmarkdown parameterized reports, how do i parameterize my rmarkdown reports

Id: oFKb8WYDLB0

Length: 19min 47sec (1187 seconds)

Published: Mon Sep 07 2020

Reddit Comments

[u/Sir_smokes_a_lot]

Thanks for the video. I’ve been having a hard time grasping parameterized reporting.

[u/exona]

This is the best / most useful R video I've seen in a long time! I'm working in .rmd right now and this really helped!

[u/punktdefault]

Nice video!

One thing I didn't fully grasp was the usage of map functions. As I understood your video, on gives a data frame (or tibble) as input to params but where do you implement the map function? In the code chunks following in the Markdown document?

And adding to that: How do you handle the different filenames when using above mentioned method?

[u/ADONIS_VON_MEGADONG]

RemindMe! 14 hours "RMarkdown Parameterized Reports"

[u/jinnyjuice]

Very cool, I thought these were only available for Shiny.