geocompr/geocompr repository overview

⁠Geocomputation with R in Docker

This repo documents Docker images for geographic research and reproducing code in the book Geocomputation with R. The Dockerfiles build on work done for the Rocker Project⁠ by Carl Boettiger, Dirk Eddelbuettel and Noam Ross. As documented on the Rocker Project website, Docker can save time by removing pain and reducing time associated with setting-up your operating system to work with the latest geographic packages.

To get started, after you install Docker⁠, try running one of the following commands:

# The latest version of rocker/geospatial + geocompr dependencies
docker run -e PASSWORD=pw --rm -p 8786:8787 geocompr/geocompr
# With up-to-date OSGeo packages and qgisprocess:
docker run -e PASSWORD=pw --rm -p 8786:8787 geocompr/geocompr:qgis-ext

Then open a browser at http://localhost:8786/⁠ and you should see something like this:

If so congratulations 🎉 you can proceed to open the geocompr.Rproj project or other files in the geocompr folder, which contains a complete copy of the source code and example data needed to build the html version of the book.

To run a container without RStudio, try the following.

docker run -e PASSWORD=pw --rm -ti geocompr/geocompr /bin/bash

Use this resource to play with the examples, develop new answers to the questions at the end of each page, or even to generate reproducible examples to illustrate issues⁠ with the books contents.

If not, see documentation on using Docker at websites such as docker.com⁠ and https://www.rocker-project.org/⁠.

⁠Sharing folders with Docker

To use these Docker images for your own work you will need to share files with Docker. That means sharing ‘volumes’. You can do this using the -v argument as shown below, which shares your current working directory with the Docker container. If you run these commands in a terminal that has access to Docker, like bash or Windows PowerShell you should get a local copy of Geocomputation with R on your computer that you can use for testing and development purposes, e.g. to test changes before submitting a Pull Request to improve the book:

# download repo with Windows Powershell or a Unix terminal
git clone https://github.com/Robinlovelace/geocompr.git 
# or download manually from https://github.com/Robinlovelace/geocompr/archive/master.zip
cd geocompr # navigate into the repo
# on linux and mac with password:
docker run -d -p 8786:8787 -v $(pwd):/home/rstudio/data -e USERID=$UID -e PASSWORD=pw geocompr/geocompr
# on linux and mac without password:
docker run -d -p 8786:8787 -e DISABLE_AUTH=TRUE -v $(pwd):/home/rstudio/geocompr  geocompr/geocompr
# on windows without a password:
docker run -d -p 8786:8787 -v ${pwd}:/home/rstudio/data -e DISABLE_AUTH=TRUE robinlovelace/geocompr

If you see something like this after following the steps above, congratulations: it worked! See github.com/rocker-org⁠ for more info.

From this point to build the book you can open projects in the geocompr directory from the project box in the top-right hand corner, and knit index.Rmd with the little knit button above the the RStudio script panel (Ctl+Shift+B should do the same job).

There are various versions of the geocompr Docker image available. The default is the latest tag, representing the Dockerfile in the root of this repo, but you can get other images, as outlined below.

⁠Versions

Building on the rocker-org⁠ project, we provide various versions for testing and development, including builds that use more up-to-date versions of OSGeo packages such as GDAL provided by the UbuntuGIS software repository⁠, as shown below:

image	description	size
geocompr:latest⁠	rocker/geospatial:latest base image
geocompr:buildbook⁠	rocker/geospatial:latest with built version of the book
geocompr:dev-osgeo⁠	rocker/geospatial:dev-osgeo base image, with recent versions of GDAL, PROJ and GEOS
geocompr:dev-osgeo-b⁠	rocker/geospatial:dev-osgeo base image
geocompr:ubuntugis_unstable⁠	UbuntuGIS unstable repos on Ubuntu 18.04
geocompr:python⁠	geocompr/geocompr with Python
geocompr:qgis⁠	geocompr/geocompr with QGIS
geocompr:qgis-dev⁠	geocompr/geocompr with dev version of QGIS
geocompr:qgis-ext⁠	geocompr/geocompr with QGIS, GRASS, SAGA & R package qgisprocess

The base image is rocker/geospatial from github.com/rocker-org/rocker-versioned2⁠.

Add :tagname to geocompr/geocompr to get the tag you’re interested in.

To run the buildbook version (represented by the extension -b for most tags), for example, run the following command (with port and password set to a port of your preference):

docker run -e PASSWORD=pw --rm -p 8786:8787 geocompr/geocompr:buildbook

⁠Examples

⁠Python

The Python tag contains Python geospatial packages:

docker run -e PASSWORD=pw --rm -ti geocompr/geocompr:python /bin/bash

python3
import pandas as pd
import geopandas as gpd
import movingpandas as mpd

⁠QGIS

To run QGIS from the command line, you can run:

docker run -e PASSWORD=pw --rm -ti geocompr/geocompr:qgis /bin/bash
qgis --version
# qgis_process

You can also run QGIS algorithms via the qgisprocess package as follows:

docker run -d -p 8786:8787 -v $(pwd):/home/rstudio/data -e PASSWORD=pw geocompr/geocompr:qgis

Then open a browser and the local url such as http://192.168.0.99:8786/⁠ or http://localhost:8786⁠, enter RStudio server, and you should be able to access QGIS as follows in the R console:

system("qgis --version")
## QGIS 3.16.1-Hannover 'Hannover' (b381a90dca)
remotes::install_github("paleolimbot/qgisprocess") # install the latest version of the package
qgis_algs = qgisprocess::qgis_algorithms()
nrow(qgis_algs)
## [1] 303
table(qgis_algs$provider)
##    3d   gdal native   qgis 
##     1     55    196     51 

⁠QGIS extensions

You can access algorithms from other GIS programs through QGIS but they need to be installed. These can be accessed from the geocompr/geocompr:qgis-ext image as follows:

docker run -d -p 8786:8787 -v $(pwd):/home/rstudio/data -e PASSWORD=pw geocompr/geocompr:qgis-ext

Again, open the browser, e.g. at http://localhost:8786⁠, and find the new algorithms as follows:

system("qgis --version")
QGIS 3.16.1-Hannover 'Hannover' (b381a90dca)
## QGIS 3.16.1-Hannover 'Hannover' (b381a90dca)
remotes::install_github("paleolimbot/qgisprocess") # install the latest version of the package
## Skipping install of 'qgisprocess' from a github remote, the SHA1 (6e378511) has not changed since last install.
qgis_algs = qgisprocess::qgis_algorithms()
nrow(qgis_algs)
## [1] 970
table(qgis_algs$provider)

##    3d   gdal grass7 native   qgis   saga 
##     1     55    301    196     51    366 

Congratulations, you now have nearly 1000 QGIS algorithms at your disposal from the R command line 🎉

⁠Building the images locally

You can build the images locally, e.g. as follows:

docker build qgis-ext -t test
docker run -p 8888:8888 test-binder