Skip to content

Commit 01fce88

Browse files
author
Christopher Prener
committed
add draft index and setup files
1 parent 6a90bc0 commit 01fce88

2 files changed

Lines changed: 275 additions & 8 deletions

File tree

‎index.md‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,23 @@ layout: lesson
33
root: .
44
---
55

6-
Data Carpentry's aim is to teach researchers basic concepts, skills, and tools for working with data so that they can get more done in
7-
less time, and with less pain. This workshop uses a FIXME dataset and teaches FIXME.
6+
Data Carpentry's aim is to teach researchers basic concepts, skills, and tools for working with data so that they can get more done in less time, and with less pain. This workshop uses a FIXME dataset and teaches FIXME.
87

98

10-
> ## Prerequisites
9+
> ## Getting Started
1110
>
12-
> There are no pre-requisites, and the materials assume no prior knowledge about the tools.
11+
> This lesson assumes no prior experience with the tools covered in the workshop.
12+
> Participants should bring their laptops and plan to participate actively.
13+
>
14+
> To get started, follow the directions in the [Setup](setup/) tab to
15+
> get access to the required software and data for this workshop.
16+
>
17+
> Please note that workshop materials for working with Geospatial data in R are under development and will become available
18+
> in June 2018.
1319
{: .prereq}
1420

1521
> ## Data
16-
>
22+
>
1723
> The data for this workshop are is the [FIXME](FIXME) available on FigShare, with a CC-BY license available for reuse.
1824
>
1925
> FIXME add a short description about the dataset.
@@ -24,7 +30,7 @@ less time, and with less pain. This workshop uses a FIXME dataset and teaches FI
2430
The workshop is taught using R.
2531

2632

27-
# Workshop Overview
33+
# Workshop Overview
2834

2935
| Lesson | Overview |
3036
| ------- | ---------- |

‎setup.md‎

Lines changed: 263 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,267 @@
11
---
22
layout: page
33
title: Setup
4-
root: .
4+
permalink: /setup/
55
---
6-
FIXME
6+
7+
# Overview
8+
9+
This workshop is designed to be run on your local machine. To do this, you will need to install all of the software used in the workshop and obtain a copy of the dataset. It is also possible to use a Docker image instead of installing the software locally. The Docker image we use allows participants to run a virtual installation of `R`, RStudio, and the necessary dependencies through their browser with streamlined installation process. Instructions for both of these options are below.
10+
11+
## Option A: Local Installation
12+
13+
### Software
14+
15+
| Software | Install | Manual | Available for | Description |
16+
| -------- | ------------ | ------ | ------------- | ----------- |
17+
| [GDAL](http://www.gdal.org) | [Link](http://www.gdal.org/usergroup0.html) | [Link](http://www.gdal.org) | Linux, MacOS, Windows | Geospatial model for reading and writing a variety of formats |
18+
| [GEOS](https://trac.osgeo.org/geos) | [Link](https://trac.osgeo.org/geos) | [Link](http://geos.osgeo.org/doxygen/) | Linux, MacOS, Windows | Geometry models and operations |
19+
| [PROJ.4](http://proj4.org) | [Link](http://proj4.org/install.html)| [Link](http://proj4.org/index.html)| Linux, MacOS, Windows | Coordinate reference system transformations |
20+
| [R](https://www.r-project.org) | [Link](https://cloud.r-project.org) | [Link](https://cloud.r-project.org) | Linux, MacOS, Windows | Software environment for statistical and scientific computing |
21+
| [RStudio](https://www.rstudio.com) | [Link](https://www.rstudio.com/products/rstudio/download/#download) | | Linux, MacOS, Windows | GUI for R |
22+
| [UDUNITS](https://www.unidata.ucar.edu/software/udunits/) | [Link](https://www.unidata.ucar.edu/downloads/udunits/index.jsp) | [Link](https://www.unidata.ucar.edu/software/udunits/#documentation) | Linux, MacOS, Windows | Unit conversions |
23+
24+
### QuickStart Software Installation Instructions
25+
26+
These are the QuickStart installation instructions. At points, they assume familiarity with the command line and with installation in general. As there are different operating systems and many different versions of operating systems and environments, these may not work on your computer. If an installation doesn't work for you, please refer to the installation instructions for that software, listed in the table above.
27+
28+
### R
29+
Participants who do not already have `R` installed should download and install it.
30+
31+
> ## Windows
32+
>
33+
>To install `R`, Windows users should select "Download R for Windows" from RStudio and CRAN's [cloud download page](https://cloud.r-project.org), which will automatically detect a CRAN mirror for you to use. Select the `base` subdirectory after choosing the Windows download page. A `.exe` executable file containing the necessary components of base R can be downloaded by clicking on "Download R 3.x.x for Windows".
34+
>
35+
{: .solution}
36+
37+
> ## macOS
38+
>
39+
>To install `R`, macOS users should select "Download R for (Mac) OS X" from RStudio and CRAN's [cloud download page](https://cloud.r-project.org), which will automatically detect a CRAN mirror for you to use. A `.pkg` file containing the necessary components of base R can be downloaded by clicking on the first available link (this will be the most recent), which will read `R-3.x.x.pkg`.
40+
>
41+
{: .solution}
42+
43+
> ## Linux
44+
>
45+
>To install `R`, Linux users should select "Download R for Linux" from RStudio and CRAN's [cloud download page](https://cloud.r-project.org), which will automatically detect a CRAN mirror for you to use. Instructions for a number of different Linux operating systems are available.
46+
>
47+
{: .solution}
48+
49+
### RStudio
50+
RStudio is an GUI for using R that is available for Windows, macOS, and various Linux operating systems. It can be downloaded [here](https://www.rstudio.com/products/rstudio/download/). You will need the **free** Desktop version for your computer.
51+
52+
### GDAL, GEOS, and PROJ.4
53+
54+
The installation of the geospatial libraries GDAL, GEOS, and PROJ.4 varies significantly based on operating system. These are all dependencies for `sf`, the `R` package that we will be using for spatial data operations throughout this workshop.
55+
56+
> ## Windows
57+
>
58+
>To install the geospatial libraries, install the latest version [RTools](https://cran.r-project.org/bin/windows/Rtools/)
59+
>
60+
{: .solution}
61+
62+
> ## macOS
63+
>
64+
> For participants who do not already have [homebrew](https://brew.sh) installed, and who may be less comfortable with the command line, the easiest was to obtain the geospatial libraries is to install the latest version of [Kyng Chaos's pre-built package](http://www.kyngchaos.com/software/frameworks) for GDAL Complete. Be aware that several other libraries are also installed, including the UnixImageIO, SQLite3, and `NumPy`.
65+
>
66+
> Alternatively, participants who are comfortable with the command line can install the geospatial libraries individually using [homebrew](https://brew.sh):
67+
>
68+
>~~~
69+
>$ brew tap osgeo/osgeo4mac && brew tap --repair
70+
>$ brew install proj
71+
>$ brew install geos
72+
>$ brew install gdal2 --with-armadillo --with-complete --with-libkml --with-unsupported
73+
>$ brew link --force gdal2
74+
>~~~
75+
>{: .bash}
76+
>
77+
{: .solution}
78+
79+
> ## Linux
80+
>
81+
> Steps for installing the geospatial will vary based on which form of Linux you are using. These instructions are adapted from the [`sf` package's `README`](https://github.com/r-spatial/sf).
82+
>
83+
> For **Ubuntu**:
84+
>
85+
>~~~
86+
>$ sudo add-apt-repository ppa:ubuntugis
87+
>$ sudo apt-get update
88+
>$ sudo apt-get install libgdal-dev libgeos-dev libproj-dev
89+
>~~~
90+
>{: .bash}
91+
>
92+
> For **Fedora**:
93+
>
94+
>~~~
95+
>$ sudo dnf install gdal-devel proj-devel proj-epsg proj-nad geos-devel
96+
>~~~
97+
>{: .bash}
98+
>
99+
> For **Arch**:
100+
>
101+
>~~~
102+
>$ pacman -S gdal proj geos
103+
>~~~
104+
>{: .bash}
105+
>
106+
> For **Debian**: The [rocker geospatial](https://github.com/rocker-org/geospatial) Dockerfiles may be helpful. Ubuntu Dockerfiles are found [here](https://github.com/r-spatial/sf/tree/master/inst/docker).
107+
>
108+
{: .solution}
109+
110+
### UDUNITS
111+
112+
Linux users will have to install UDUNITS separately. Like the geospatial libraries discussed above, this is a dependency for the `R` package `sf`. Due to conflicts, it does not install properly on Linux machines when installed as part of the `sf` installation process. It is therefore necessary to install it using the command line ahead of time.
113+
114+
> ## Linux
115+
>
116+
> Steps for installing the geospatial will vary based on which form of Linux you are using. These instructions are adapted from the [`sf` package's `README`](https://github.com/r-spatial/sf).
117+
>
118+
> For **Ubuntu**:
119+
>
120+
>~~~
121+
>$ sudo apt-get install libudunits2-dev
122+
>~~~
123+
>{: .bash}
124+
>
125+
> For **Fedora**:
126+
>
127+
>~~~
128+
>$ sudo dnf install udunits2-devel
129+
>~~~
130+
>{: .bash}
131+
>
132+
> For **Arch**:
133+
>
134+
>~~~
135+
>$ pacaur/yaourt/whatever -S udunits
136+
>~~~
137+
>{: .bash}
138+
>
139+
> For **Debian**:
140+
>
141+
>~~~
142+
>$ sudo apt-get install -y libudunits2-dev
143+
>~~~
144+
>{: .bash}
145+
>
146+
{: .solution}
147+
148+
### R Packages
149+
150+
The following `R` packages are used in the various geospatial lessons.
151+
152+
* [`dplyr`](https://cran.r-project.org/package=dplyr)
153+
* [`ggplot2`](https://cran.r-project.org/package=ggplo2)
154+
* [`sf`](https://cran.r-project.org/package=sf)
155+
* [`raster`](https://cran.r-project.org/package=raster)
156+
* [`rgdal`](https://cran.r-project.org/package=rgdal)
157+
* [`rasterVis`](https://cran.r-project.org/package=rasterVis)
158+
159+
To install them from the `R` prompt, type:
160+
161+
```r
162+
install.packages(c("dplyr", "ggplot2", "sf", "raster", "rgdal", "rasterVis"))
163+
```
164+
165+
## Option B: Docker
166+
167+
[Docker](https://www.docker.com) provides developers with a means for creating "containers" that contain pre-installed software. These containers can be downloaded and used locally, allowing end-users to get software up and running quickly, particularly when a local installation of the software could be complex and time consuming. For `R` users, a Docker image can be used to create a virtual installation of `R` and RStudio that can be run through your web browser.
168+
169+
Option B involves downloading an Docker image that contains an installation of `R`, RStudio Server, all of the necessary dependencies listed above, and almost all of the `R` packages used in the geospatial lessons. You will need to install the appropriate version of Docker's Community Edition software and then download and open the `rocker/geospatial` Docker image.
170+
171+
> ## Downloading and Installing Docker Community Edition
172+
>
173+
> To get started with Docker, download the [Docker Community Edition](https://www.docker.com/community-edition) from [Docker's store](https://store.docker.com/search?type=edition&offering=community). Community editions are available for [Windows](https://store.docker.com/editions/community/docker-ce-desktop-windows), [macOS](https://store.docker.com/editions/community/docker-ce-desktop-mac), and Linux operating systems including [Debian](https://store.docker.com/editions/community/docker-ce-server-debian), [Fedora](https://store.docker.com/editions/community/docker-ce-server-fedora), and [Ubuntu](https://store.docker.com/editions/community/docker-ce-server-ubuntu).
174+
>
175+
> The download pages for each of these operating systems contain notes about some necessary system requirements and other pre-requisites. Once you download the installer and follow the on-screen prompts.
176+
>
177+
> Additional installation notes are available in Docker's documentation for each of these operating systems: [Windows](https://docs.docker.com/docker-for-windows/install/), [macOS](https://docs.docker.com/docker-for-mac/install/), [Debian](https://docs.docker.com/install/linux/docker-ce/debian/), [Fedora](https://docs.docker.com/install/linux/docker-ce/fedora/), and [Ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/).
178+
>
179+
{: .solution}
180+
181+
> ## Using the `rocker/geospatial` Docker Image via the Command Line
182+
>
183+
> #### Download and Set-up
184+
> Once Docker is installed and up and running, you will need to open your computer's command line terminal. We'll use the terminal to download [`rocker/geospatial`](https://github.com/rocker-org/geospatial), a pre-made Docker image that contains an installation of `R`, RStudio Server, all of the necessary dependencies, and all but one of the `R` packages needed for this workshop.
185+
>
186+
> To get started, make sure Docker is running and then enter the following command into the terminal to download the `rocker/geospatial` image:
187+
>
188+
>~~~
189+
>$ docker pull rocker/geospatial
190+
>~~~
191+
>{: .bash}
192+
>
193+
> Once the pull command is executed, the image needs to be run to become accessible. When `docker run` is used, you can specify a folder on your computer to become accessible inside your RStudio Server instance. The following `docker run` command exposes Jane's `GitHub` directory to RStudio Server:
194+
>
195+
>~~~
196+
>$ docker run -d -P --name gis /Users/jane/GitHub:/home/rstudio/GitHub rocker/geospatial
197+
>~~~
198+
>{: .bash}
199+
>
200+
> When she opens her RStudio instance below, she will see a `GitHub` folder in her file table in the lower righthand corner of the screen. Windows and Linux users will have to adapt the file path above to follow the standards of their operating systems. More details are available on [rocker's Wiki](https://github.com/rocker-org/rocker/wiki/Sharing-files-with-host-machine).
201+
>
202+
> Each Docker image can be run via multiple containers. In this example, the image is named `rocker/geospatial` and the container is named `gis`. For example, Jane could also create a separate container based off the `rocker/geospatial` image named `geospatial`. New Docker users should need only one named container based on an image.
203+
>
204+
> The last step before launching your browser is to identify the port that your Docker container is running in:
205+
>
206+
>~~~
207+
>$ docker port gis
208+
>~~~
209+
>{: .bash}
210+
>
211+
> An output, for example, of `8787/tcp -> 0.0.0.0:32768` would indicate that you should point your browser to `http://localhost:32768/`. If prompted, enter `rstudio` for both the username and the password.
212+
>
213+
> #### Stopping a Container
214+
> When you are done with a Docker session, make sure all of your files are saved locally on your computer **before closing Docker**. Once you have ensured all of your files are available (they should be saved at the file path designated in `docker run` above), you can stop your Docker image in the terminal:
215+
>
216+
>~~~
217+
>$ docker stop gis
218+
>~~~
219+
>{: .bash}
220+
>
221+
> #### Re-starting a Container
222+
> Once an image has been downloaded, named, and created, you cannot create an image with the same name again using `docker run`. Instead, you can restart it:
223+
>
224+
>~~~
225+
>$ docker start gis
226+
>~~~
227+
>{: .bash}
228+
>
229+
> If you cannot remember the name of the image you created, you can use the following command to print a list of all named containers:
230+
>
231+
>~~~
232+
>$ docker ps -a
233+
>~~~
234+
>{: .bash}
235+
>
236+
{: .solution}
237+
238+
> ## Managing Docker Resources
239+
> To obtain a list of all of your current Docker containers:
240+
>
241+
>~~~
242+
>$ docker ps -a
243+
>~~~
244+
>{: .bash}
245+
>
246+
> To list all of the currently downloaded Docker images:
247+
>
248+
>~~~
249+
>$ docker images -a
250+
>~~~
251+
>{: .bash}
252+
>
253+
> These images can take up system resources, and if you'd like to remove them, you can use the `docker prune` command. To remove any Docker resources not affiliated with a container listed under `docker ps -a`:
254+
>
255+
>~~~
256+
>$ docker system prune
257+
>~~~
258+
>{: .bash}
259+
>
260+
> To remove **all** Docker resources, including currently named containers:
261+
>
262+
>~~~
263+
>$ docker system prune -a
264+
>~~~
265+
>{: .bash}
266+
>
267+
{: .solution}

0 commit comments

Comments
 (0)