In MariekeDirk/Reproducability-Reusability-course: Course example package
knitr::opts_chunk$set(echo = TRUE)
#themes: “default”, “cerulean”, “journal”, “flatly”, “readable”, “spacelab”, “united”, “cosmo”, “lumen”, “paper”, “sandstone”, “simplex”, “yeti"
Introduction
Reproducibility of research is becoming more and more important (Nature special). If we can't reproduce research results, how can we use them for future research? What is the value of irreproducible conclusions? To improve reproducibility training is important to boost reproducibility (Nature,2016).
During this course we will introduce you to tools to make your code reproducible and re-usable for other researchers. As it's not possible to introduce you to all software we made a selection. Our focus will be on the reproducibility of code by introducing you to:
- Git
- GitHub
- Rprojects, including code documentation in R and testing functions
- Travis CI
Course schedule
The course is given at the KNMI. Make sure you bring a passport or ID card. We meet in the reception hall downstairs.
| Time | Description |
|------|-------------|
| 09:00-09:15 | Welcome & Coffee |
| 09:15-09:30 | Introduction |
| 09:30-10:30 | Git & GitHub |
| 10:30-10:45 | Coffee break |
| 10:45-11:00 | R projects structure |
| 11:00-11:30 | R Markdown |
| 11:30-12:00 | Documentation of code |
| 12:00-13:00 | Lunch Break |
| 13:00-14:30 | Putting it all together: combining Rstudio with GitHub |
| 14:30-14:45 | Coffee Break |
| 14:45-15:15 | Test your function |
| 15:15-16:00 | Documentation of data |
| 16:00-17:00 | Round up practicals & time for questions |
| 17:00-17:30 | Drinks |
Additional material:
- Relevant literature
- Protect your code with Travis CI
- Take home messages
- How to do this at home for your own code
What do I need for this course?
- A GitHub account
- Travis CI account (you can signup with your GitHub account)
- The code and instruction manual, can be found here
Git and GitHub
Git
Below an example of how git works. We start from scratsh by creating a test directory and a test file test.txt. We are going to change the content of the file, and revert the changes.
```{bash, eval=FALSE}
cd ~./Documents/test
mkdir test
cd test
echo something > test.txt
ls
cat test.txt
git help
git config --global user.name "Your Name Comes Here"
git config --global user.email you@yourdomain.example.com
git init
git add test.txt
git commit -m 'first commit'
echo test > test.txt
git commit -am 'commiting something which is wrong...'
git reset HEAD~
cat test.txt
My suggestion would be to make this session interactive with some exercises.
The following topics I would suggest for this course:
Git:
* Local version control
* Using git to modify a .txt file with some text
* Practice commit & revert
GitHub:
* Introduction (movie or something): Collaboration multiple people
* Private vs. Public
* Branches
* Push and Pull
* Forking someone's repo
## Suggested reading
* [git tutorial](https://git-scm.com/docs/gittutorial)
# R projects
## Package structure
## Loading a the code from GitHub
1. Go to the [scource code](https://github.com/MariekeDirk/Reproducibility-Reusability-course.git) on GitHub and Fork the repository to your own account
2. Copy the https link using the button clone or download.
3. Go to Rstudio, click on file, new project, version controls, git and paste the link. You can now work on the project from your own computer.
## R Markdown
## Documentation of code
Function are saved in the R folder. To document the function roxygen2 is used. Below an example of a function with documentation:
```r
#'
#'@title Square area
#'@description Function to calculate the area of a square. Requires numeric input.
#'@param length The length of the square [m]
#'@param width The width of the square [m]
#'@examples
#'square_area(4,5)
#'
#'\dontrun{
#'square_area(4,"5")}
#'@author Marieke Dirksen
#'@export
#'
square_area<-function(length,width){
if(!inherits(length,"numeric") | !inherits(width,"numeric")) {
message("Your length or width is not numeric")
return(FALSE)
} else {
area<-length*width
return(area)
}
}
square_area(3,4)
The function description is stored in .Rd files (folder man). To add your function description to the documentation of your package use:
library(devtools)
devtools::document()
Excercise 3.1
Create your own Function and document the code in a .Rd file.
Suggestions:
- Calculate the area of a circle
- Volume of a shpere
- Mean value from random numbers
Putting it all together: combining Rstudio with GitHub
Now you have created your own function in the project, documented the code and solved all errors and warnings its time for the next step: Putting your code back on GitHub.
Some suggestions for the course:
- config git user.name and user.email global
- commit changes
- push the changes to your github
- merge the forked branch with the master
If there is more time:
- revert changes
- stash and other options
Test your function
Sometimes your make small changes to your code without generating warnings or errors. It can however occur that the output of your function did change. To ensure that for the same input the function always generates the same output test functions are written. The test function in this package looks like this:
context("test square area")
test_that("square area equal",{
expect_equal(square_area(3,4),12)
})
Excercise 3.2
Write a testthat function. An example is included in tests/testthat/
For more information check out the R journal on testthat
Excercise 3.3
Test the different options to built and reload your package.
There are buttons below Build, but you can use key combinations like: Ctrl+Shift+B, Ctrl+Shift+T and Ctrl+Shift+E
Fix posible errors and warnings
Documentation of datasets
Example Jurian
Suggested reading
Appendix A: Relevant literature
Personally I also put a suggested reading at the end of each chapter, we could make a list of all the suggested reading and
additional information here.
Appendix B: Take home messages
- course package
- Most important lessons learned
- DIYS instructions
Appendix C: Protect your code with Travis CI
Points to include:
- Short overview of other systems checking your code
- What travis does and why it is usefull for your research
- Travis CI is used to check your code you put on GitHub. You can login with your GitHub account.
- To include Travis CI to your repository check this website.
- To see if your branch passes the test you can add an image
To this repository the .travis.yml file includes the following code:
language: R
sudo: false
cache: packages
Excercise 5.1
Put your repositories on Travis CI and pass the test.
Excercise 5.2
(a) Create a branch with an error
(b) Merge a failed branch with the master
(c) Revert the changes...we want a master without errors/warnings
(d) Make your master branch protected
(e) Try to merge the failed branch again
MariekeDirk/Reproducability-Reusability-course documentation built on May 12, 2019, 1:07 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
knitr::opts_chunk$set(echo = TRUE) #themes: “default”, “cerulean”, “journal”, “flatly”, “readable”, “spacelab”, “united”, “cosmo”, “lumen”, “paper”, “sandstone”, “simplex”, “yeti"
Introduction
Reproducibility of research is becoming more and more important (Nature special). If we can't reproduce research results, how can we use them for future research? What is the value of irreproducible conclusions? To improve reproducibility training is important to boost reproducibility (Nature,2016).
During this course we will introduce you to tools to make your code reproducible and re-usable for other researchers. As it's not possible to introduce you to all software we made a selection. Our focus will be on the reproducibility of code by introducing you to:
- Git
- GitHub
- Rprojects, including code documentation in R and testing functions
- Travis CI
Course schedule
The course is given at the KNMI. Make sure you bring a passport or ID card. We meet in the reception hall downstairs.
| Time | Description | |------|-------------| | 09:00-09:15 | Welcome & Coffee | | 09:15-09:30 | Introduction | | 09:30-10:30 | Git & GitHub | | 10:30-10:45 | Coffee break | | 10:45-11:00 | R projects structure | | 11:00-11:30 | R Markdown | | 11:30-12:00 | Documentation of code | | 12:00-13:00 | Lunch Break | | 13:00-14:30 | Putting it all together: combining Rstudio with GitHub | | 14:30-14:45 | Coffee Break | | 14:45-15:15 | Test your function | | 15:15-16:00 | Documentation of data | | 16:00-17:00 | Round up practicals & time for questions | | 17:00-17:30 | Drinks |
Additional material:
- Relevant literature
- Protect your code with Travis CI
- Take home messages
- How to do this at home for your own code
What do I need for this course?
- A GitHub account
- Travis CI account (you can signup with your GitHub account)
- The code and instruction manual, can be found here
Git and GitHub
Git
Below an example of how git works. We start from scratsh by creating a test directory and a test file test.txt. We are going to change the content of the file, and revert the changes. ```{bash, eval=FALSE} cd ~./Documents/test mkdir test cd test echo something > test.txt ls cat test.txt
git help git config --global user.name "Your Name Comes Here" git config --global user.email you@yourdomain.example.com git init git add test.txt git commit -m 'first commit'
echo test > test.txt
git commit -am 'commiting something which is wrong...'
git reset HEAD~ cat test.txt
My suggestion would be to make this session interactive with some exercises. The following topics I would suggest for this course: Git: * Local version control * Using git to modify a .txt file with some text * Practice commit & revert GitHub: * Introduction (movie or something): Collaboration multiple people * Private vs. Public * Branches * Push and Pull * Forking someone's repo ## Suggested reading * [git tutorial](https://git-scm.com/docs/gittutorial) # R projects ## Package structure ## Loading a the code from GitHub 1. Go to the [scource code](https://github.com/MariekeDirk/Reproducibility-Reusability-course.git) on GitHub and Fork the repository to your own account 2. Copy the https link using the button clone or download. 3. Go to Rstudio, click on file, new project, version controls, git and paste the link. You can now work on the project from your own computer.  ## R Markdown ## Documentation of code Function are saved in the R folder. To document the function roxygen2 is used. Below an example of a function with documentation: ```r #' #'@title Square area #'@description Function to calculate the area of a square. Requires numeric input. #'@param length The length of the square [m] #'@param width The width of the square [m] #'@examples #'square_area(4,5) #' #'\dontrun{ #'square_area(4,"5")} #'@author Marieke Dirksen #'@export #' square_area<-function(length,width){ if(!inherits(length,"numeric") | !inherits(width,"numeric")) { message("Your length or width is not numeric") return(FALSE) } else { area<-length*width return(area) } } square_area(3,4)
The function description is stored in .Rd files (folder man). To add your function description to the documentation of your package use:
library(devtools) devtools::document()
Excercise 3.1
Create your own Function and document the code in a .Rd file.
Suggestions:
- Calculate the area of a circle
- Volume of a shpere
- Mean value from random numbers
Putting it all together: combining Rstudio with GitHub
Now you have created your own function in the project, documented the code and solved all errors and warnings its time for the next step: Putting your code back on GitHub.
Some suggestions for the course:
- config git user.name and user.email global
- commit changes
- push the changes to your github
- merge the forked branch with the master
If there is more time:
- revert changes
- stash and other options
Test your function
Sometimes your make small changes to your code without generating warnings or errors. It can however occur that the output of your function did change. To ensure that for the same input the function always generates the same output test functions are written. The test function in this package looks like this:
context("test square area") test_that("square area equal",{ expect_equal(square_area(3,4),12) })
Excercise 3.2
Write a testthat function. An example is included in tests/testthat/
For more information check out the R journal on testthatExcercise 3.3
Test the different options to built and reload your package.
There are buttons below Build, but you can use key combinations like: Ctrl+Shift+B, Ctrl+Shift+T and Ctrl+Shift+E Fix posible errors and warnings
Documentation of datasets
Example Jurian
Suggested reading
Appendix A: Relevant literature
Personally I also put a suggested reading at the end of each chapter, we could make a list of all the suggested reading and additional information here.
Appendix B: Take home messages
- course package
- Most important lessons learned
- DIYS instructions
Appendix C: Protect your code with Travis CI
Points to include:
- Short overview of other systems checking your code
- What travis does and why it is usefull for your research
- Travis CI is used to check your code you put on GitHub. You can login with your GitHub account.
- To include Travis CI to your repository check this website.
- To see if your branch passes the test you can add an image
To this repository the .travis.yml file includes the following code:
language: R sudo: false cache: packages
Excercise 5.1
Put your repositories on Travis CI and pass the test.
Excercise 5.2
(a) Create a branch with an error (b) Merge a failed branch with the master (c) Revert the changes...we want a master without errors/warnings (d) Make your master branch protected (e) Try to merge the failed branch again
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.