Building the project

Initial Setup

Clone the visualization repository. You can do this in RStudio by choosing File | New Project... | Version Control | Git and pasting in the Repository URL you copied from GitHub (green "Clone or download" button).

If you don't have it, install vizlab. If the project has a specific tagged version of vizlab, you can install this using devtools::install_github("USGS-VIZLAB/vizlab@tagname").

do:

library(vizlab)

then make sure you have the proper packages and versions installed with:

vizlab::checkVizPackages()

and use install.packages() or devtools::install_github() to update.

To get the svglite package, use devtools::install_github("jread-usgs/svglite@svgnano"). For Windows users, you might see an error similar to Error: running command '"C:/PROGRA~1/R/R-34~1.1/bin/x64/R" --no-site-file --no-environ --no-save --no-restore --quiet CMD config CC' had status 127. If this is the case, clone Jordan Read's repository and build the package locally on the branch svgnano.

Building

Run the following command in R to build the project:

vizmake()

You can also just build specific phases:

vizmake('Fetch')

or specific viz items:

vizmake('county_boundaries_topojson')

Once you are able to complete the build, see https://github.com/USGS-VIZLAB/vizlab/wiki/Previewing-visualizations to view the results.

While developing vizlab

If you've updated the vizlab package and want to try the new code in an open R session for a vizzy, run

detach("package:vizlab", unload = TRUE)
library(vizlab)

and the new code will then be available.

Debugging with remake

With remake, you can call vizmake on any viz item and/or its file location.

vizmake('iris-data')
vizmake('data/iris.csv')

If it's a readable file, you can also assign the output to an R object for inspection.

dat <- vizmake(iris-data')

Vizlab also allows you to build individual viz items at the R console by calling the phase-specific function on the viz item:

fetch('iris-data')
process('cuyahoga')

and if necessary you can read these items outside the remake framework like this:

dat <- readData('iris-data')

The difference between calling vizmake and, say, process is that vizmake will build any out-of-date upstream dependencies first. Therefore you should usually call vizmake rather than process, but there might be times when temporarily out-of-date is preferable to waiting a long time for previous steps to build.

When debugging functions within the R or remake systems, you have two good options. You can insert this line within the function you want to debug:

browser()

or you can tell R to debug a specific function and then run vizmake, publish, etc. as usual:

debug(vizlab:::visualize.qTDS)
vizmake('cuyahogaFig')

and then when you're done debugging:

undebug(vizlab:::visualize.qTDS)