-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
223 lines (151 loc) · 13.9 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
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
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/",
out.width = "100%"
)
```
# gravityshop <a href="https://paezha.github.io/gravityshop/"><img src="man/figures/logo.png" align="right" height="200" /></a>
<!-- badges: start -->
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[](https://github.com/paezha/gravityshop/stargazers)
<!-- badges: end -->
Package {gravityshop} is an open educational resource to teach a workshop on spatial interaction analysis using `R` and computational notebooks.
The package aims to combine various advantages of working with the [`R` statistical computing project](https://www.r-project.org/):
- Ease of distribution
- Reproducibility
- Availability of templates for computational notebooks
- Rigor in documentation of data sets and computational products
The package is designed for use in a 6-session workshop (approximately 12 hours) that teaches the principles of principles of spatial interaction analysis, including the peculiarities of interaction data, exploratory techniques, and modelling using the gravity model, all using `R`. The package includes the following components:
- Document templates with _Sessions_
- Data sets used in the _Sessions_ or for individual practice/research
The _Sessions_ are [R markdown](https://rmarkdown.rstudio.com/) documents with the main contents of the workshop. These documents resemble lecture notes, but with a difference: they are [literate programming](https://en.wikipedia.org/wiki/Literate_programming) documents that are are interactive and editable, which means that you can work with them in ways not possible with conventional printed notes.
## Workshop outline
### Session 1. Basics of working with `R` (2 h)
- Why `R`?
- Installing the software: `R` and R Studio
- Packages
- Installing packages: CRAN and other sources
- Getting help
- (Break)
- Creating a project
- Directory structure
- Creating new files: types of files
- Literate programming
- Data objects/classes and basic operations
### Session 2. What is special about interaction data? (2 h)
- Why measuring things?
### Session 3. Visualization of interaction data (2 h)
- What is EDA?
### Session 4. The gravity model for spatial interaction: Basic concepts (2 h)
- Why visualization?
### Session 5. The gravity model for spatial interaction: Implementation (2 h)
- Reading external data
### Session 6. The gravity model for spatial interaction: Implementation (2 h)
- Reading external data
### Session 7. A date with the gravity model: Bring your own data (2 h)
- Reading external data
## What do I need to use this package?
The workshop does not assume knowledge of, or experience working with `R`. So, no previous knowledge regarding the software/language is required, besides experience using computers in general, and maybe a word processor (e.g., Microsoft Word) and spreadsheets (e.g., Microsoft Excel). To use the package you will begin from the very basics: how to install and use the necessary software: `R` and an Interactive Development Environment (e.g., RStudio) as explained next.
### `R`: The open statistical computing project
What is `R`?
`R` is an open-source language for statistical computing. It was created in the early 1990s by [Ross Ihaka](https://en.wikipedia.org/wiki/Ross_Ihaka) and [Robert Gentleman](https://en.wikipedia.org/wiki/Robert_Gentleman_(statistician)) at the University of Auckland, New Zealand, as a way to provide their students with an accessible, no-cost statistical application for their courses. `R` is now maintained by the `R` Development Core Team, and it continues to be developed by hundreds of contributors around the globe. `R` is an attractive alternative to other software packages for data analysis (e.g., Microsoft Excel, Matlab, Stata, ArcGIS) due to its open-source character (i.e., it is free), its flexibility, and large user community. The size of the `R` community means that if there is something you want to do (for instance, estimate a linear regression model or plot geographical information), it is very likely that someone has already developed a package for it in `R`.
A good way to think about `R` is as a core package, with a library of optional packages that can be attached to increase its core functionality. `R` can be downloaded for free at:
https://CRAN.R-project.org/
`R` comes with a built-in console (a graphical user interface), but better alternatives to the basic interface include Interactive Development Environments like RStudio, which can also be downloaded for free:
https://www.rstudio.com/products/rstudio/download/
`R` requires you to work using the command line, which is going to be unfamiliar to many of you accustomed to user-friendly graphical interfaces. Do not fear. People worked for a long time using the command line, or using even more cumbersome systems, such as punched cards in early computers. Graphical user interfaces are convenient, but they have a major drawback, namely their inflexibility. A program that functions based on graphical user interfaces allows you to do only what is hard-coded in the user interface. Command line, as you will soon discover, is somewhat more involved, but provides much more flexibility in operation, and the ability to be more creative.
To begin, install `R` and RStudio in your computer. This [video](https://www.youtube.com/watch?v=gZh91IdIMts) (5:23 min) shows how to install these applications.
If you have used `R` and have a previous instal, update it to `R` version 4.2.0 (2022-04-22) -- "Vigorous Calisthenics". **The package was developed using “Vigorous Calisthenics”!**
### RStudio window: A Quick Tour
RStudio is an _Interactive Development Environment_ (IDE for short). It takes the form of a familiar window application, and it provides a complete interface to interact with the language `R`. The application consists of a window with toolbars and several panes. Some panes include several tabs. There are the usual drop-down menus for common operations. See Figure 1 below.
```{r echo=FALSE}
knitr::include_graphics("man/figures/01-RStudio-Window-Anatomy.png")
```
__Figure 1.__ _RStudio IDE_
The editor pane allows you to open and work with text and other files. In these files you can write instructions that can be passed on to `R` for execution. Writing something in the editor does not execute the instructions, it merely records them for possible future use.
The console pane is where instructions are passed on to the program. When an instruction is typed (or copied and pasted) there, `R` will understand that it needs to do something. The instructions must be written in a way that `R` understands, otherwise errors will occur.
The top-right pane includes a tab for the environment; this is where all data objects that are currently in memory are reported. The History tab in the same pane acts like a log: it keeps track of all instructions that have been executed in the console. Depending on your project, you may see other tabs there.
The last pane in the bottom-right includes a few other useful tabs. The File tab allows you to navigate directories in your computer, change the working directory, see what files are where, and so on. The Plot tab is where plots are rendered, when instructions require `R` to do so. The Packages tab allows you to manage packages, which as mentioned above, are pieces of code that can augment the functionality of `R`. The Help tab is where you can consult the documentation for functions/packages/see examples, and so on. The Viewer tab is for displaying web content locally. Many `R` functions create html output and it is in this pane where this kind of content can be previewed.
## Quick Start Guide
Once you have installed `R` and RStudio you are ready to install the package {gravityshop}. The package is available from [GitHub](https://github.com/paezha/gravityshop), and to install it you need to run the following code in your `R` console:
``` r
install.packages("remotes")
remotes::install_github("paezha/gravityshop")
```
This will download the package to your personal library of packages and install it to make the package available for use locally. Behind the scenes, {envsocty3LT3} uses LaTeX to convert documents to PDF. For this you need to have install LaTeX in your system. The simplest approach on any platform is with `R` package [tinytex](https://yihui.org/tinytex/), as follows:
```{r eval=FALSE}
install.packages(c('tinytex', 'rmarkdown'))
tinytex::install_tinytex()
```
After restarting R Studio, confirm that you have LaTeX with the following command:
```{r eval=FALSE}
tinytex:::is_tinytex()
```
## Recommended Workflow
After installing the package, this is the recommended workflow for using it in the workshop.
### Create a project for all your work in this workshop
Follow the steps below to create a new project. A project is the best way to keep your work in this workshop nicely organized.
You can create a new project using the buttons in the toolbar. Figure 2 shows one way of doing this:
```{r echo=FALSE}
knitr::include_graphics("man/figures/02-Create-Project-1.gif")
```
__Figure 2.__ _Create new project - option 1_
Figure 3 shows an alternative way of doing the same, using the button for managing projects in the R Studio interface:
```{r echo=FALSE}
knitr::include_graphics("man/figures/03-Create-Project-2.gif")
```
__Figure 3.__ _Create new project - option 2_
You then need to select a new directory to store your new project. Give the new directory a name, and save it in a place that you can easily find (for instance, the folder where you keep your academic work). Figure 4 illustrates the steps to do this:
```{r echo=FALSE}
knitr::include_graphics("man/figures/04-Create-Project-Directory.gif")
```
__Figure 4.__ _Choose to store the project in a new directory_
After you click 'Create Project', you will have an `R` session with your new project. This will look like the image in Figure 5.
```{r echo=FALSE}
knitr::include_graphics("man/figures/05-New-Project.png")
```
__Figure 5.__ _Your project keeps all your files nicely organized_
### Working with templates
You need to restart R Studio once after installing the package before you can access the file templates for the _Sessions_.
After restarting the application, you will find that the templates are available when you choose to create a new R Markdown file. To work with templates, you start by creating a new R Markdown file with the option of using a template. As an example, select template `eda-session-1-IT` from package {gravityshop} and give it a name. The instructor will indicate which specific files to use (the example is for the Italian Edition of the workshop). After you click 'OK', a new R Markdown file will open in your editor. Also, notice that a new folder appears in your project to keep this file. The process is illustrated in Figure 6.
```{r echo=FALSE}
knitr::include_graphics("man/figures/06-New-File-Session.gif")
```
__Figure 6.__ _Creating a new file from a template_
Your new file is an R Markdown document. This is a text file with _chunks_ of code that can be executed. `eda-session-1-*` will introduce you to the use of R Markdown, literate programming, and the basics of working with `R`. The document is editable, which means that you can annotate it. To begin with, you can add your name to the list of authors of the document. You can execute code by clicking on the 'play' icon on the top-right corner of a chunk of code. The template also includes a definition for a _textbox_. You can introduce a textbox in the text using this format:
```
:::{.textbox data-latex=""}
This is my annotation.
:::
```
Figure 7 illustrates these steps.
```{r echo=FALSE}
knitr::include_graphics("man/figures/07-Working-with-Template.gif")
```
__Figure 7.__ _Working with a computational notebook_
Once you are happy with your work using this file, you can create a pdf file (for archiving or to study) by _knitting_ the document. Knitting will convert the R Markdown to a pdf file. Click the Knit button in the top left corner to do this. You can knit your document at any time, and as many times as you want; remember, you can always start afresh by creating a new R Markdown file with the same template. See Figure 8 for an example of knitting.
```{r echo=FALSE}
knitr::include_graphics("man/figures/08-Knitting.gif")
```
__Figure 8.__ _Click 'Knit' on the toolbar to convert your R Markdown into a pdf file_
Figure 9 shows the result of knitting your R Markdown file.
```{r echo=FALSE}
knitr::include_graphics("man/figures/09-Knitted-Session.gif")
```
__Figure 9.__ _The result of knitting is a pdf file with your workshop notes_
Since you can edit and annotate the text, you can essentially _customize_ the document so that it is a unique reflection of your learning. As you progress with the workshop and complete all the sessions, you will have a collection of _unique_ documents that track your very personal learning experience.