generated from jhudsl/OTTR_Template
-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy path04-OCS_Modification.Rmd
119 lines (73 loc) · 7.12 KB
/
04-OCS_Modification.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
```{r, include = FALSE, eval = FALSE}
ottrpal::set_knitr_image_path()
```
# Modifying open case studies
## Learning Objectives
This chapter will cover how to modify the case studies to your own needs using the following methods:
- Modular case study use with the help of the [`OCSdata` package](https://github.com/opencasestudies/OCSdata)
- Modifying a case study with [GitHub](https://github.com/opencasestudies) and [RStudio](https://www.rstudio.com/)
## Modular use
Some educators may find that only certain sections of a case study are relevant to their specific needs. For example, a statistics teacher may want students to practice the skills covered in the data analysis section, but doesn't have time to go through the whole case study. The case studies are designed to allow for such use. This educator and their students may jump right in to any case study section without working through any previous sections. This is made possible because the data files are saved at the end of each section. These data files are made available on the case study's GitHub repository and may also be downloaded with the help of the `OCSdata` package. See Chapter 2 for more details on the structure and organization of a case study data folder. The table below explains which data sub-folder and package function to use for each case study section.
| Data Folder | Case Study Section | `OCSdata` Function |
| ----- | -------- | ------ |
| raw | Data Import | `raw_data` |
| imported | Data Exploration, Data Wrangling | `imported_data` |
| wrangled | Data Visualization, Data Analysis | `wrangled_csv`, `wrangled_rda` |
| simpler_import | Data Import | `simpler_import_data` |
| extra | Suggested Homework (?) | `extra_data` |
If you'd like to learn more about modular use of Open Case Studies you can read this [thesis](https://jscholarship.library.jhu.edu/handle/1774.2/66820) by former graduate student [Michael Breshock](https://mbreshock.github.io/) @breshock_expanding_2021.
### Example of Modular Use
The following steps illustrate how one would skip to a specific case study section. The data analysis section from the "Opioids in United States" case study is used for this example, but these directions apply for any section in any case study.
#### Steps for modular use
1) Use the table of contents to navigate to the section of interest. Click on the arrow that reads "If you skipped the previous sections click here."
```{r, fig.align='center', echo = FALSE, fig.alt= "Video showing a user skipping to the data analysis section of a case study", out.width="100%"}
knitr::include_url('https://www.youtube.com/embed/Z4WZ7A0OZF8')
```
2) Follow the instructions provided to download the data files from the previous section either with `OCSdata` or manually through GitHub. We will now demonstrate each option.
#### Downloading data with `OCSdata`:
1) First install and load the `OCSdata` package:
```{r, include = TRUE, eval = FALSE}
install.packages("OCSdata") #only run once to install package
library(OCSdata) #run every new R session to load package
```
2) Now download the wrangled data into your R environment using the following function command:
```{r, include = TRUE, eval = FALSE, comment = FALSE}
wrangled_rda("ocs-bp-opioid-rural-urban", outpath = getwd())
```
*This command will download the wrangled data in .RDA format. You may also be downloaded wrangled data in .CSV format by replacing 'wrangled_rda' with 'wrangled_csv'*
3) Load the RDA files with the following commands:
```{r, include = TRUE, eval = FALSE, comment = FALSE}
load(file = here::here("OCS_data", "data", "wrangled", "Annual_opioid_data.rda"))
load(file = here::here("OCS_data", "data", "wrangled", "county_info.rda"))
```
#### Manually Download Data from GitHub:
1) Download the .RDA files available on the case study GitHub repository from [here](https://github.com/opencasestudies/ocs-bp-opioid-rural-urban/tree/master/data/wrangled).
*The CSV versions of the files may also be downloaded here, if preferred*
2) Move the data files from your 'Downloads' folder to your R session's current working directory (you can see what this is with ```getwd()```).
3) Load the RDA files with the following commands:
```{r, include = TRUE, eval = FALSE, comment = FALSE}
load(file = here::here("Annual_opioid_data.rda"))
load(file = here::here("county_info.rda"))
```
3) All the data you need to work through the current section is now loaded into your environment. You are ready to work through the section of interest, without needing to work through any of the previous sections.
## Modify a case study
The case studies are written in [R Markdown](https://rmarkdown.rstudio.com/) documents and developed within an RStudio project. R Markdown documents are denoted with the file extension ".Rmd" and allow for the inclusion of code chunks and outputs in a written report. They are written using [Markdown syntax](https://raw.githubusercontent.com/rstudio/cheatsheets/main/rmarkdown.pdf). RStudio projects are used to organize the case studies. The [knitr](https://yihui.org/knitr/) package "knits" the case study written in R Markdown and outputs the document as an HTML file. Open Case Studies uses these HTML files to post the case studies online. The entire case study project is contained in a GitHub repository which allows for easy distribution and version control. [GitHub Pages](https://pages.github.com/) is used to host the case study webpage from the case study repository.
Modifying a case study requires the following simple steps:
1. Use the `OCSdata` package `zip_ocs()` function to download the case study files without our git history. Alternatively, if you are familiar with GitHub and wish to you can clone or fork the case study repository from GitHub. See [this section](https://www.opencasestudies.org/OCS_Guide/open-case-study-infrastructure.html#fork-or-clone-the-case-study-repository) of chapter 2 for more information.
2. In the repository folder, open the case study .Rproj file to open the project up in RStudio.
3. Edit the sections to be modified in the index.Rmd file.
4. Save your changes, then click on the "Knit" drop down menu in the top left corner of RStudio. Choose which file format you'd like to knit to.
```{r, fig.align='center', echo = FALSE, fig.alt= "Screenshot of RStudio window with Knit button highlighted in red and drop down menu showing. Window also shows the Opioids case study repository with the index.Rmd file opened.", out.width="100%"}
knitr::include_graphics('resources/images/rstudio_modify_knit_red.png', dpi = NA)
```
5. Distribute your modified case study as you please!
You can share HTML, PDF and Word files directly with your students or you can host your case study for free on GitHub using [GitHub pages](https://pages.github.com/) [@pages_github].
To do so, you will need to set up your version of the case study on GitHub. If you are new to GitHub, also be sure to check out @happygitwithr.
These steps are demonstrated in the following video about modifying case studies:
```{r, fig.align="center", fig.alt = "video", echo=FALSE, out.width="100%"}
knitr::include_url("https://www.youtube.com/embed/UFs4qvgTuTw")
```
## Session info
```{r, echo = FALSE}
sessionInfo()
```