forked from statnmap/teach-package-dev-rmdfirst
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathsubmission.Rmd
129 lines (88 loc) · 7.79 KB
/
submission.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
120
121
122
123
124
125
126
127
128
129
---
title: 'How to build a package with "Rmd First" method'
author: "Sébastien Rochette"
date: "28/01/2021"
output: html_document
---
## The title of the tutorial
How to build a package with "Rmd First" method
## Abstract
"Rmd First" method can reduce mental load when building packages by keeping users in a natural environment, using a tool they know: a RMarkdown document.
The step between writing your own R code to analyze some data and refactoring it into a well-documented, ready-to-share R package seems unreachable to many R users.
The package structure is sometimes perceived as useful only for building general-purpose tools for data analysis to be shared on official platforms.
However, packages can be used for a broader range of purposes, from internal use to open-source sharing.
Because packages are designed for robustness and enforce helpful standards for documentation and testing, the package structure provides a useful framework for refactoring analyses and preparing them to go into production.
The following approach to write a development or an analysis inside a Rmd, will significantly reduce the work to transform a Rmd into a package :
- _Design_ : define the goal of your next steps and the tools needed to reach them
- _Prototype_ : use some small examples to prototype your script in Rmd
- _Build_ : Build your script as functions and document your work to be able to use them, in the future, on real-life datasets
- _Strengthen_ : Create tests to assure stability of your code and follow modifications through time
- _Deploy_ : Transform as a well-structured package to deploy and share with your community
During this tutorial, we will work through the steps of Rmd Driven Development to persuade attendees that their experience writing R code means that they already know how to build a package. They only need to be in a safe environment to find it out, which will be what we propose.
We will take advantage of all existing tools such as {devtools}, {testthat}, {attachment} and {usethis} that ease package development from Rmd to building a package.
The recent package [{fusen}](https://thinkr-open.github.io/fusen), which "inflates a package from a simple flat Rmd", will be presented to further reduce the step between well-designed Rmd and package deployment.
Attendees will leave this workshop having built their first package with the "Rmd First" method and with the skills and tools to build more packages on their own.
## The broad topic it covers
- R Packages: building packages, CRAN submission and package maintenance
- Reproducibility and best practices
## The learning goals
By the end of the tutorial participants should:
- understand the methodology proposed by Rmd Driven Development
- be able to refactor their code into correctly formatted functions
- understand the structure of a package
- be able to build a documented and tested R package
- know how to share their work with the community on GitHub
## Time zone preference and time slot (please mention at least three different time zones you are comfortable with)
- 1:00pm - 4:00pm UTC
- 2:00pm - 5:00pm UTC
- 3:00pm - 6:00pm UTC
## Length of the tutorial
Tutorial will be 3 hours length.
It will be divided in 3 times 1 hour: ~25’ presentation + 2’ quizz + 28’ exercises + 5’ break
## Language in which the tutorial can be taught.
The tutorial will be taught in English.
However, there will be a possibility for help in French during exercises sessions.
## The intended audience and method of online engagement with the audience
The course will alternate between two formats of instruction:
- Plenary room : Lecture, presenting slides
- Breakout rooms (if possible): Exercises time. 5 attendees by room (6 rooms). Instructors are not needed in all 6 rooms, but we want to be able to discuss with some, without bothering everyone. Instructors will move from a room to the other and may be summoned over Slack. Teaching assistants may be needed.
The tutorial is built as a private course.
- There will only be 30 participants for 3 instructors.
- Attendees are expected to participate and to answer questions.
- Instructors will make sure this participation will be in a safe environment, in plain group and in small groups during exercises.
- Instructors will ask questions to individuals to be sure no one is left behind.
- Attendees should expect to share their screen individually or to the group so that we can help.
- Instructors will try to make the course active and exciting. Attendees are expected to help in this way.
A chat platform (Slack or equivalent) will be open in parallel to allow chat assistance, attendees interactions and information or resources sharing.
## If there exists, a link to the Tutorial materials and/or web page.
- https://github.com/statnmap/user2021.rmdd
## Prerequisites / requirements
### Prerequisites
Upper-beginner to Intermediate.
Attendees should already have experience with R and be able to:
- Manipulate rectangular data with {dplyr}: select, filter, mutate, group_by, summarize
- Work with RMarkdown documents
- Understand the meaning of this line of code and how to use it:
```
my_mean <- function(x, na.rm = TRUE) { sum(x, na.rm = na.rm) / length(x) }
```
### Requirements
- The tutorial will be taught using the [ThinkR e-learning platform, named CRUZ](https://rtask.thinkr.fr/remote-trainings-and-certification/).
Here is a presentation of the platform that will be provided: https://thinkr.fr/Take_a_tour_on_CRUZ.pdf
- The platform provided by ThinkR is online. No installation is required on attendees computers.
- Attendees will only receive their credentials the day before the tutorial. They will be able to log on the e-learning platform after receiving their credentials.
- All attendees will have their own sessions with all required packages and course material already installed
- Required equipment
+ A computer
+ A correct internet connection (You can test your internet connection: we recommend a download value higher than 6 Mb/s)
+ A microphone (*compulsory, the default computer mic is perfect*), a webcam if the learner wishes and has one (*possibly the computer’s one if available*), headphones to ensure the learner’s comfort – the ideal being a headset with a microphone
+ Good mood 🙂
## Material sharing (license), recording consent
- Material will be shared on GitHub : https://github.com/statnmap/user2021.rmdd
- Instructors agree to be recorded. Attendees will be notified when recording is on, in particular during plenary room sessions. Recording will be stopped (or deleted) during exercises time
## A brief biography of the instructors
- Sébastien Rochette (@statnmap) is R trainer and consultant at [ThinkR](https://rtask.thinkr.fr).
He participates in the development of open-source R packages proposed on GitHub by ThinkR and himself, including {fusen} and {attachment}. He also has created multiple internal packages for ThinkR and different clients.
He gave different presentations and tutorials on package development with the 'Rmd first' method as summed up in ["Rmd first: When development starts with documentation"](https://rtask.thinkr.fr/when-development-starts-with-documentation/) and blogs about R [on his website](https://statnmap.com).
He is co-author of the book ["Engineering Production-Grade Shiny Apps"](https://engineering-shiny.org/) that promotes an adapted RMDD method for Shiny application using {golem}.
- Emily Riederer (@emilyriederer) is a Senior Analytics Manager at Capital One where she leads a team building analytics infrastrucutre in R. Emily is a proponent of [R Markdown Driven Development](https://emilyriederer.netlify.app/post/rmarkdown-driven-development/) and a co-author of the [R Markdown Cookbook](https://bookdown.org/yihui/rmarkdown-cookbook/). She also maintains the {projmgr} and {convo} R packages, and frequently blogs about R [on her website](emily.rbind.io).