This course will assist you with recreating work that a previous coworker completed, revisiting a project you abandoned some time ago, or simply reproducing a document with a consistent format and workflow. Incomplete information about how the work was done, where the files are, and which is the most recent version can give rise to many complications. This course focuses on the proper documentation creation process, allowing you and your colleagues to easily reproduce the components of your workflow. Throughout this course, you'll receive helpful demonstrations of RStudio and the R Markdown language and engage in active learning opportunities to help you build a professional online portfolio.
Communicating to Your Team on How to Use Your Templates and Projects
Loading...
En provenance du cours de Emory University
Reproducible Templates for Analysis and Dissemination
4 notes
À partir de la leçon
Working in Teams and Disseminating Templates and Reports
This module focuses on helpful tips for sharing and using the templates you create, as well as methods for organizing content. We'll also look at a few web-publishing services.
Rencontrer les enseignants
Melinda HigginsAssociate Research Professor/Senior Biostatistician
School of Nursing
In the previous lesson, you saw how to leverage both RPubs and
GitHub to publish examples of the types of documents that can be produced
using your reproducible templates.
We did this by providing web links in your README file on your GitHub repository.
However, simply providing examples of your reports is not enough.
You should also provide the following information to
people using your templates.
Number one, what kind of data and format does your report template expect.
For example, the weather article needed the weather check data set that was built
into the 538 R package.
Number two, the file components that are needed to support your template.
For example, the WC base RND template document assumes that
the components are contained in three sub folders for text, images, and code.
Number three, you need descriptions of each of the document components,
what is actually in each file, and what the purpose of that file is.
And number four, it's always good to provide instructions to people wanting to
use your templates of any assumptions or dependencies that they need to know?
For example, can a child text documents or the child R scripts be used in any order?
In our example for the WC base template we could easily switch the order of
the two child text documents that swap the order of the purpose and the background.
For example, the purpose could come before the background section.
Likewise, we could switch the order of the R scripts such that the R code
that makes the clustered bar chart could come before the code that makes
the demographics table.
However, both of these R scripts assume that the set-up script had already been
run, because that loads the R packages and the weather-check dataset.
So the set-up script has to come first at the beginning of the document.
It would be good to include these kinds of instructions in your README file.
I'm going to leave this as an exercise to do on your own.
But take some time to customize your README file.
You may also want to share these instructions with a colleague or
a friend, and see if they can follow your instructions well enough
to use your GitHub repository and the associated files
to build their own reports using your template and instructions.
Some other ways to communicate to people how to use your templates
can be accomplished by providing vignettes.
And you can do this through our packages.
You can learn more about creating R packages and specifically about adding
a vignettes to your R package at Karl Broman's tutorial on writing vignettes.
And the link was provided in the read ahead materials.
So let's add a vignettes to your WCTemplatePackage.
And we created this in module four.
So let's open RStudio and we're going to open that project for WCTemplatePackage.
Let's open a file explorer window and go to RepTemplates for
your WCTemplatePackage.
And in this folder we're going to create a new subfolder called vignettes.
And then in this folder we're actually going to copy over the wcArticle
file from your WCtemplateSimple project and
we're going to paste it in the WCtemplatePackage for vignettes.
After you've got a copy of the wcArticle in your vignettes folder go ahead and
open it here in RStudio edit window.
To make this work as a vignette we actually have to make some edits
to the YAML header.
For right now, we don't need all of these parameters.
So we're actually going to go in and delete the choices and
input select and just delete that from the button of your YAML header information.
For right now, we're just going to leave this set where the region is set to
the value for mountain.
The next change that we need to make to the YAML header is we're going to change
the output from HTML document to vignette document.
We can take a look at what Karl Broman has here in his tutorial.
So we're actually going to change the output, and
we need to add some code here on how to build the vignette.
We're actually going to add this to the bottom of the YAML header, and
we're going to remove the previous output statement for HTML document.
Go ahead and click save.
Now that we've made these changes to the wcArticle rmarkdown file,
we also need to make some change to the description file.
Open your description file, and at the bottom we need to add two more lines.
We need to add in a line for suggests that lists the knitr and
rmarkdown packages and a line for VignetteBuilder
that says to use the knitr package to build the vignettes, click save.
Now that we've made the changes to the description and
the wcArticle rmarkdown file, we need to next build the vignettes for your package.
We're going to do that by typing a command Into the console window into RStudio.
devtools build_vignettes.
When you click this it begins building the vignettes for your package.
When it completes you'll notice that is says that it was copying
some information into a new folder under ints/doc.
So if we click on the ints folder in addition to the rmarkdown folder that
we had previously.
We now have a folder for doc, and there's three new files.
We have an HTML, an R, and the rmarkdown file for the wcArticle.
These have now been added to your package.
Let's go ahead and
use Git Bash to sync these up with the changes to the repository.
Make sure that you're in the folder for your WCtemplatePackage and
typing git status to see the changes that you've made.
Type git add to add the files, git commit and
we'll say that we've added the vignette.
Type in git push to sync everything up with your cloud account and
then type git status.
So go back to the GitHub repository for your WCtemplatePackage.
And click refresh to see the updates that were just added.
Now that we've made all these changes to your package,
we're going to re-install it with the updated vignette.
We're going to use the devtools command for installing off of a GitHub repository,
so let's type in devtools::install_github.
Make sure that you use the link for your GitHub account.
In our studio, go ahead and click on the packages tab and
scroll down to where you can see the WCtemplatePackage installed.
If you click on this link, it brings up the help file for your package.
At the top, you're going to see a link for user guides, package vignettes, and
other documentation.
And when you click on this,
it brings up a page that lists any vignettes that come with your package.
If you had more than one, they'd be listed right here.
Let's go ahead and click on the link for the wcArticle to see the HTML for
this template.
This now is the vignette for your package.
This is just a quick example.
But you could spend some time developing rmarkdown files
to create different vignettes that illustrate different types of templates or
layouts and options that are possible with your R package.
One example to get ideas is the CRAN website for the dplyr package.
When you bring this up, you'll notice that there's a listing here for vignettes.
They actually have five.
These five vignettes illustrate different capabilities of the dplyr package.
Back in RStudio we can click on packages and
scroll to the link for the dplyr package.
And again, if we click on user guides package of vignettes and
other documentation.
Again, you'll see these same five vignettes listed here in the help window.
So now you've learned three different ways of communicating information and
instructions to others on how to use your templates and packages.
You can publish examples using RPubs.
You can use HTML files using GitHub pages and docs folder of your GitHub repository.
And if you convert your template project into an R package,
you can use vignettes to illusrtate how to use your package.
And through the R package, you really have a fourth way of communicating,
through the template itself, which is available to others when they create a new
rmarkdown template after they install your package.
So the template itself can actually provide instructions and
details on how to use your template.
Explorer notre catalogue
Rejoignez-nous gratuitement et obtenez des recommendations, des mises à jour et des offres personnalisées.
Coursera propose un accès universel à la meilleure formation au monde,
en partenariat avec des universités et des organisations du plus haut niveau, pour proposer des cours en ligne.
© 2018 Coursera Inc. Tous droits réservés.
