Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
174 lines (143 sloc) 6.98 KB
---
title: "Introduction to prodigenr"
author: "Luke W. Johnston"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Introduction to prodigenr}
%\VignetteEngine{knitr::rmarkdown}
---
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
eval = FALSE
)
```
Are you an academic researcher who often writes up abstracts for conferences or
submits manuscripts to journals? Do you often have to make slides or posters for
presentations? Is your usual workflow to copy a previous project and start
replacing the old text for the new text? This R package was designed with you in
mind!
`prodigenr`, or *pro*ject *di*rectory *gen*erator, simplifies the process of
creating these new projects and can help make your workflow more reproducible.
Standard files and folders are created for specific projects (e.g. abstracts or
manuscripts), along with a workflow that tries to be simple and easy to use,
while making use of the infrastructure and processes already well-developed and
maintained (e.g. RStudio and devtools).
Because researchers often write or create many papers, slides, posters, and
abstracts, it can quickly become tedious and messy to always make a new
directory with all the necessary files and organization.
## The main command: `setup_project`
To use `prodigenr`, you start with using the `setup_project()` command. At
present, there are only four template projects that you can view using:
```{r templates}
library(prodigenr)
template_list
```
These templates are projects that an academic researcher typically encounters.
However, if you have a suggestion or want to add a template, please create a
[Github issue](https://github.com/lwjohnst86/prodigenr/issues) or submit a [Pull Request](https://github.com/lwjohnst86/prodigenr/pulls)!
Starting a manuscript? Create a project directory like so (using [Git](https://git-scm.com/)):
```{r manuscriptProj}
path <- tempdir()
setup_project("HeartDiseaseExercise", path)
```
```{r shell_command, echo=FALSE, eval=FALSE}
# run only on computer
cat(paste(system(
paste0('cd ', path, '/HeartDiseaseExercise && tree -a -I ".git|.Rproj.user" --dirsfirst -v'),
intern = TRUE
), collapse = '\n'),
file = 'file_structure.txt')
```
The resulting file structure should look something like this:
```{r file_structure, echo=FALSE, eval=TRUE, results='markup', comment=''}
cat(readLines('file_structure.txt', warn = FALSE), sep = '\n')
```
Ok, now you can open up the newly created R project file (`.Rproj`). To add the
main document type (e.g. poster, manuscript), run any of the `create_*()`
commands (e.g. `create_poster()`) in the console of the project.
```{r poster_abstract_show, eval=FALSE}
# you need to run these in the project's console
create_abstract()
create_poster()
```
```{r poster_abstract_hide, echo=FALSE}
# you need to run these in the project's console
withr::with_dir(
file.path(path, "HeartDiseaseExercise"),
{
create_abstract()
create_poster()
}
)
```
Which will now add two more files to the `doc/` folder.
```{r shell_command_doc, echo=FALSE, eval=FALSE}
# run only on computer
cat(paste(system(
paste0('cd ', path, '/HeartDiseaseExercise && tree -a -I ".git|.Rproj.user" --dirsfirst -v'),
intern = TRUE
), collapse = '\n'),
file = 'file_structure_with_doc.txt')
```
The resulting file structure should look something like this:
```{r file_structure_with_doc, echo=FALSE, eval=TRUE, results='markup', comment=''}
cat(readLines('file_structure_with_doc.txt', warn = FALSE), sep = '\n')
```
A `README.md` file is contained within each project and each folder that
explains more about what each folder does and what some of the files do that
were created.
The end goal of each project is to be as self contained as possible. So that if
you ever need to go back to the analysis, it is easy to re-run the code and get
the results that you say you got. This is especially useful if others such as
reviewers ask for something or want to confirm your results. For more
information on good practices to use in making an analysis project, see
[here](http://stats.stackexchange.com/questions/2910/how-to-efficiently-manage-a-statistical-analysis-project)
or
[here](http://www.r-bloggers.com/managing-a-statistical-analysis-project-%E2%80%93-guidelines-and-best-practices/). See the [manifesto](manifesto.html) for more details on
the underlying philosophy behind this package (and soon to be others).
## Workflow when using projects created from `prodigenr`
A typical workflow, which is also outlined in the README.md of the created
project, would be to:
1. Write up your analysis and associated written explanations of the results, as
you would for any research project, in the abstract, poster, slides, or
manuscript `.Rmd` ([R Markdown](http://rmarkdown.rstudio.com/)) file in the
`doc/` folder.
2. Any piece of code you use more than once or is fairly complex, convert it
into a function. Put this new function into a file (or a `functions.R` file) in the
`R/` directory. Load that function using `devtools::load_all()` (Ctrl-Shift-L).
3. Fetch and wrangle your data in the `R/fetch_data.R`. You can access the
data using the `devtools::load_all()` function.
4. Create more Rmd files in the `doc/` folder to add analyses that will
supplement the main document or that are exploratory.
5. Knit the `.Rmd` file in `doc/`. You now have your final abstract, poster,
slides, or manuscript to use for your research.
## Related packages or projects
There are several ways of handling a project. There is at least two packages
that have similar goals as `prodigenr` as well as through the use of the R
package structure:
- [`ProjectTemplate`](http://projecttemplate.net/) is well documented and still
actively developed. Only downside is that it is fairly complicated to use and
complex in the project workflow it creates.
- [`makeProject`](https://cran.r-project.org/package=makeProject)
is very simple and stripped down in what it creates and in it's use. Downside is
that it wasn't updated since 2012.
- Use of the R package structure via
[`devtools`](https://cran.r-project.org/package=devtools) (or
[`usethis`](https://cran.r-project.org/package=usethis)),
which is argued for in this
[blog](https://rmflight.github.io/posts/2014/07/vignetteAnalysis.html) and
compared to `ProjectTemplate` in this
[blog](https://rmflight.github.io/posts/2014/07/zpackages_vs_projectTemplate.html)).
- [`rrtools`](https://github.com/benmarwick/rrtools) is very similar to prodigenr,
except it focuses only on manuscripts. Is well thought out and the documentation
is well written.
- [`workflowr`](https://github.com/jdblischak/workflowr) is a workflow for creating
online, data science content.
There is also a list of other similar projects
[on the rOpenSci GitHub repository](https://github.com/ropensci/rrrpkg#useful-tools-and-templates-for-making-research-compendia).
It's up to you to decide which style to use.
If you have ideas to improve prodigenr, just submit a
[GitHub issue](https://github.com/lwjohnst86/prodigenr/issues)!
You can’t perform that action at this time.