-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathREADME.Rmd
108 lines (60 loc) · 6.15 KB
/
README.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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```
# What is this?
This repository is an experimental demonstratation of how you might combine a research compendium created by [rrtools](https://github.com/benmarwick/rrtools) with Binder, a service that creates an executable environment with RStudio in your browser. This means you can work on your compendium, writing the paper and code on any computer with a web browser and internet connection. This also makes your code immediately reproducible by anyone, anywhere. Scroll right to the bottom of this readme to find the pink button that will start Binder for this repository.
## How to try it out?
To try this yourself, [fork this repo](https://github.com/benmarwick/blank-research-compendium#fork-destination-box), then edit this README.Rmd file to edit the pink 'lauch binder' button in at the bottom of this readme so that it launches from your repository. Change it from:
`[](http://mybinder.org/v2/gh/benmarwick/blank-research-compendium/master)`
to replace benmarwick with your GitHub username:
`[](http://mybinder.org/v2/gh/yourusername/blank-research-compendium/master)`
Then knit, commit and push this change to your GitHub repository. Once it has updated, click on the pink 'launch binder' button in your README on your repository to start the Binder service in your browser. First you will see the loading screen, which looks like this:
Then you will see the file list for your Jupyter Notebook, something like this:
And from here you can start RStudio via the 'New' window, like this:
Now you have RStudio running in your browser, with all your files from your GitHub repository available to work on, like this:
You can work in RStudio, in your browser, and then use Git commands in the RStudio terminal to save your changes to your GitHub repository. Note that this is discouraged by the Binder developers because [they cannot guarantee the security of data moving through their service](https://mybinder.readthedocs.io/en/latest/faq.html#can-i-push-data-from-my-binder-session-back-to-my-repository)
## Limitations
- Binder is under active development and subject to breaking changes.
- Binder is not suitable for big files and analyses involving big/long computes.
- Binder gives you [1 GB RAM](https://mybinder.readthedocs.io/en/latest/faq.html#user-memory)
- Binder will give you 12 hours of session time per user session, but will time-out after [10 min of inactivity](https://mybinder.readthedocs.io/en/latest/faq.html#how-long-will-my-binder-session-last)
- The Binder developers recommend that you should [never share sensitive or personal information within a Binder repository](https://mybinder.readthedocs.io/en/latest/faq.html#how-secure-is-mybinder-org). This includes passwords, data that shouldn’t be public, API keys, etc.
# How to use this with a research compendium?
There are two ways to use Binder with a GitHub-hosted research compendium:
1. Use Binder to write text and develop and run code in RStudio in your browser, and commit and push back to the repo to save your changes. This adds a lot of flexibility to working with research compendia because you don't need to install anything locally. If you do this, you should start by running `rrtools::use_readme_rmd()` and follow the rest ofthe [rrtools](https://github.com/benmarwick/rrtools) setup steps. As you go through these steps, you should choose 'Yes' to overwrite the README file and `analysis/` directory in this repo. You'll need to change the name of the RStudio project and compendium name in a few places. However, the Binder developers discourage using passwords in Binder because they do no guarantee the security of data moving through their service.
2. After development of research compendium is complete, and the paper is published, add a 'launch binder' button and the config files to the compendium repository on GitHub to enable others to explore the text and run the code in their browser. This is using Binder more like a display cabinet for the code, and you are not a risk of having your passwords exposed.
This section below is generated by `rrtools::use_readme_rmd()` and shows where to put the 'launch binder' button to invite users to explore your compendium:
# My Research Compendium
This repository contains the data and code for our paper:
> Authors, (YYYY). _Title of paper_. Name of journal/book <https://doi.org/xxx/xxx>
Our pre-print is online here:
> Authors, (YYYY). _Title of paper_. Name of journal/book, Accessed `r format(Sys.Date(), "%d %b %Y")`. Online at <https://doi.org/xxx/xxx>
### How to cite
Please cite this compendium as:
> Authors, (`r format(Sys.Date(), "%Y")`). _Compendium of R code and data for 'Title of paper'_. Accessed `r format(Sys.Date(), "%d %b %Y")`. Online at <https://doi.org/xxx/xxx>
### How to run download or install
You can run the code in this compendium in your browser using Binder: [](http://mybinder.org/v2/gh/benmarwick/blank-research-compendium/master)
You can download the compendium as a zip from from this URL: xxx
Or you can install this compendium as an R package, xxx, from GitHub with:
```{r eval = FALSE}
if (!require(devtools)) install.packages("devtools")
devtools::install_github("xxx/xxx")
```
### Licenses
**Text and figures :** [CC-BY-4.0](http://creativecommons.org/licenses/by/4.0/)
**Code :** See the [DESCRIPTION](DESCRIPTION) file
**Data :** [CC-0](http://creativecommons.org/publicdomain/zero/1.0/) attribution requested in reuse
### Contributions
We welcome contributions from everyone. Before you get started, please see our [contributor guidelines](CONTRIBUTING.md). Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms.