UC Davis DataLab
Winter 2022
Instructor: Michele Tobias <mmtobias@ucdavis.edu>
In this workshop, attendees will be introduced to building an interactive web map to display spatial data using the Leaflet javascript library.
In this workshop, attendees will learn
In this workshop, participants will be introduced to the following skills:
Learners should have a basic understanding of spatial data formats such as vector and raster data, as well as experience with any coding language. Learners with previous experience with coding in HTML and javascript will have an easier time learning, but these skills are not required.
This repository is a template for workshop readers for the UC Davis DataLab. This template uses bookdown to knit the reader. You can also optionally use renv to manage packages and Git Large File Storage to manage large files (instructions included).
To get started, create a new repo on GitHub from this template
(instructions), then git clone
your new repo.
Once you've cloned the repo, here's a checklist of things to do to prepare the repo:
renv (optional): To set up renv, open R at the top level of the repo and run:
renv::init()
Restart R. Then, to install the bookdown toolchain to the project package library, run:
install.packages("bookdown")
renv::snapshot()
You can skip this step if you're not going to use renv.
index.Rmd
: Replace the all-caps text with your workshop details.
output:
HTML block)output:
HTML block)README.md
: Replace the all-caps text with your workshop details.
GitHub: In the repo's About section, add the reader URL and appropriate tags.
GitHub: In the repo's Settings page, enable GitHub pages. Set the branch to
master
and the directory to docs/
.
README.md
: Remove these template instructions, which end at the # Workshop:
header below
git add
all changed files, then git commit
and git push
.
The course reader is a live webpage, hosted through GitHub, where you can enter curriculum content and post it to a public-facing site for learners.
To make alterations to the reader:
Run git pull
, or if it's your first time contributing, see
Setup.
Edit an existing chapter file or create a new one. Chapter files are R
Markdown files (.Rmd
) at the top level of the repo. Enter your text,
code, and other information directly into the file. Make sure your file:
##_topic-of-chapter.Rmd
(the only exception
is index.Rmd
, which contains the reader's front page).# This
). This will be the title
of your chapter. Subsequent section headers should be second-level
headers (like ## This
) or below.Put any supporting resources in data/
or img/
. For large files, see
Large Files. You do not need to
add resources generated by your R code (such as plots). The knit step saves
these in docs/
automatically.
Run knit.R
to regenerate the HTML files in the docs/
. You can do this
in the shell with ./knit.R
or in R with source("knit.R")
.
Run renv::snapshot()
in an R session at the top level of the repo to
automatically add any packages your code uses to the project package
library.
When you're finished, git add
:
data/
and img/
docs/
(all of it)_bookdown_files/
(contains the knitr cache)renv.lock
(contains the renv package list).gitattributes
(contains the Git LFS file list)Then git commit
and git push
. The live web page will update
automatically after 1-10 minutes.
If one of your code chunks takes a lot of time or memory to run, consider
caching the result, so the chunk won't run every time someone knits the
reader. To cache a code chunk, add cache=TRUE
in the chunk header. It's
best practice to label cached chunks, like so:
```{r YOUR_CHUNK_NAME, cache=TRUE}
# Your code...
Cached files are stored in the `_bookdown_files/` directory. If you ever want
to clear the cache, you can delete this directory (or its subdirectories).
The cache will be rebuilt the next time you knit the reader.
Beware that caching doesn't work with some packages, especially packages that
use external libraries. Because of this, it's best to leave caching off for
code chunks that are not resource-intensive.
### Large Files
If you want to include a large file (say over 1 MB), you should use git LFS.
You can register a large file with git LFS with the shell command:
```sh
git lfs track YOUR_FILE
This command updates the .gitattributes
file at the top level of the repo. To
make sure the change is saved, you also need to run:
git add .gitattributes
Now that your large is registered with git LFS, you can add, commit, and push the file with git the same way you would any other file, and git LFS will automatically intercede as needed.
GitHub provides 1 GB of storage and 1 GB of monthly bandwidth free per repo for large files. If your large file is more than 50 MB, check with the other contributors before adding it.
GitHub Actions can be set up to automatically render your reader when you push new content to a repo. If you would like to use this function, download the materials in datalab-dev/utilities/render_bookdown_site and follow the instructions there.
This repo uses Git Large File Storage (git LFS) for large files. If you don't have git LFS installed, download it and run the installer. Then in the shell (in any directory), run:
git lfs install
Then your one-time setup of git LFS is done. Next, clone this repo with git clone
. The large files will be downloaded automatically with the rest of the
repo.
This repo uses renv for package management. Install renv according to the installation instructions on their website.
Then open an R session at the top level of the repo and run:
renv::restore()
This will download and install the correct versions of all the required packages to renv's package library. This is separate from your global R package library and will not interfere with other versions of packages you have installed.