/
01-setup.qmd
187 lines (138 loc) · 6.48 KB
/
01-setup.qmd
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
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
# Setting up {#sec-setup}
[Recording](https://youtu.be/XiM4jFJ6ocY)
Create a package project and edit the default files. We'll start using the most helpful package, usethis.
Today we'll be using the following `r glossary("package", "packages")`, so install them if necessary:
```{r install, eval = FALSE, filename="Packages required for this chapter"}
library(usethis)
library(devtools)
```
You may need to download some other files to allow you to compile packages if you've never installed a package "from source" before. If you're a Windows user, you'll need [RTools](https://cran.r-project.org/bin/windows/Rtools); download and install the recommended version. If you're a Mac user, you'll need [XCode Tools](https://www.freecodecamp.org/news/install-xcode-command-line-tools/), which you can install by opening the Terminal tab in RStudio (or opening the Terminal application) and typing the following at the command line: `xcode-select --install`.
Additionally, you may need to install LaTeX to make PDF versions of the code documentation. The tinytex package is usually the easiest way to do this.
```{r, eval = FALSE, filename="run in the console"}
install.packages("tinytex")
tinytex::install_tinytex()
```
## Create your R package
Use the following command to create the framework for a new package called `demopkg`. Set the path `r glossary("argument")` to the path where you want to save your package. The last section of the path should be the name of the package: `demopkg`.
```{r create-package, eval = FALSE, filename="run in the console"}
usethis::create_package(path = "~/rproj/demopkg")
```
::: {.callout-warning}
Package names can only be letters, numbers, and full stops.
:::
You'll see the following output, and a new RStudio `r glossary("project")` will open up. You can close the old window now and just work in this project.
::: {.cell-output}
```
✔ Creating '/Users/lisad/rproj/demopkg/'
✔ Setting active project to '/Users/lisad/rproj/demopkg'
✔ Creating 'R/'
✔ Writing 'DESCRIPTION'
Package: demopkg
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R (parsed):
* First Last <first.last@example.com> [aut, cre] (YOUR-ORCID-ID)
Description: What the package does (one paragraph).
License: `use_mit_license()`, `use_gpl3_license()` or friends to
pick a license
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.2.0
✔ Writing 'NAMESPACE'
✔ Writing 'demopkg.Rproj'
✔ Adding '^demopkg\\.Rproj$' to '.Rbuildignore'
✔ Adding '.Rproj.user' to '.gitignore'
✔ Adding '^\\.Rproj\\.user$' to '.Rbuildignore'
✔ Opening '/Users/lisad/rproj/demopkg/' in new RStudio session
✔ Setting active project to '<no active project>'
```
:::
### Edit the DESCRIPTION file
Open the `DESCRIPTION` file. It should look like this:
```{yaml, filename = "DESCRIPTION"}
Package: demopkg
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R:
person("First", "Last", , "first.last@example.com", role = c("aut", "cre"),
comment = c(ORCID = "YOUR-ORCID-ID"))
Description: What the package does (one paragraph).
License: `use_mit_license()`, `use_gpl3_license()` or friends to pick a license
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.2.0
```
Change the title, authors, and description to your own information. If your package has multiple authors, add them as a vector like this. You can also add your [ORCiD](https://orcid.org/).
```{yaml, filename = "DESCRIPTION"}
Authors@R: c(
person(given = "Lisa",
family = "DeBruine",
role = c("aut", "cre"),
email = "debruine@gmail.com",
comment = c(ORCID = "0000-0002-7523-5539")),
person(given = "Firstname",
family = "Lastname",
role = c("aut"),
email = "person@gmail.com",
comment = c(ORCID = "0000-0000-0000-000X")))
```
Also add the date like this. The date is used to create an automatic citation for your package.
```{yaml, filename = "DESCRIPTION"}
Package: demopkg
Date: 2022-10-05
```
### Create a LICENSE
Make sure you've saved any changes to the `DESCRIPTION` file first, as adding a license will modify that file. Add a license using one of the following options:
```{r license, eval = FALSE, filename="run one in the console"}
# more common for study or data packages
usethis::use_ccby_license() # reusable with citation
usethis::use_cc0_license() # public domain
# more common for function packages
usethis::use_mit_license() # permissive sharing
usethis::use_gpl3_license() # derivatives must be open
```
See <https://choosealicense.com> for more details and other options.
### Create a README
Use the following code to set up a `r glossary("README")` document that will explain how to install and use your package.
```{r readme, eval = FALSE, filename="run in the console"}
usethis::use_readme_rmd()
```
We'll eventually put this on `r glossary("github")`, so change the installation instructions to the following (change `yourusername` to your github username).
```` md
You can install demopkg from [GitHub](https://github.com) with:
```{{r}}
devtools::install_github("yourusername/demopkg")
```
````
Delete the example for now.
::: {.callout-warning}
Make sure you knit your README.Rmd file when you update it and never edit the README.md file (that's just for github).
:::
We'll make a full-featured pkgdown website in @sec-pkgdown, so we don't need too many details here.
## Install the package
This package doesn't do much yet, but you can install it. Go to the Build tab of the upper right pane and click the install button (or type `devtools::install()` in the console). You should get some output that looks like this:
::: {.cell-output}
```
* installing to library ‘/Library/Frameworks/R.framework/Versions/4.2/Resources/library’
* installing *source* package ‘demopkg’ ...
** using staged installation
No man pages found in package ‘demopkg’
** help
*** installing help indices
** building package indices
** testing if installed package can be loaded from temporary location
** testing if installed package can be loaded from final location
** testing if installed package keeps a record of temporary installation path
* DONE (demopkg)
```
:::
Now you should be able to see `demopkg` in your Packages tab, load it with the `library()` function, and get a citation.
```{r, filename="run in the console"}
citation("demopkg")
```
## Glossary
```{r, echo = FALSE, results='asis'}
glossary_table()
```
## Further Practice
1. Set up another package for your own data and analysis.