Skip to contents

Build a Data Site

Source: vignettes/quickstart-site.Rmd
quickstart-site.Rmd

Built with R 4.3.1

Basic example

Building a data site consists of 3 steps:

  1. Initialize the site
  2. Add data to the site
  3. Specify the site’s layout

1. Initialize

Start by loading the library and initializing a site.

library(community)

# this can be in an existing or new directory
# for this example, it is a temporary directory
output <- paste0(tempdir(), "/example_site")
init_site(output, template = "basic")

2. Add Data

Now you should have a data folder in output where you can put your data files, and a build.R file which you can use to reformat those files if needed, and add them to the site.

# make a simple example set
data <- data.frame(
  ID = 1:78,
  matrix(rnorm(234), 78, dimnames = list(NULL, c("x", "y", "z")))
)

# write that set to a file
write.csv(data, paste0(output, "/data.csv"), row.names = FALSE)

# add it to the site
data_add("../../data.csv", dir = paste0(output, "/docs/data"))

This sets up the data’s metadata (written to datapackage.json), which the site will use when it’s built.

Including this code in build.R is not necessary, but can be a way to organize things, and make any data processing steps repeatable.

Including the original data (data.csv in this case) is not also strictly necessary – the data file made when you build the site (by default) is all that will actually be used by the site.

3. Specify

Everything to do with the look and functionality of the site happens between site.R and the site_build function.

For an initial site, replace the template content of site.R with this:

page_navbar("Site Title")
output_plot("x", "y", "z")

Then save and build the site:

site_build(output, open_after = TRUE, serve = TRUE)

open_after opens the build page in a browser, which might get annoying as you edit and rebuild the site.

serve starts a local server to view the page.

Add inputs

Inputs can be named and then referred to in outputs. For example, you might want to allow plot variables to be changed. To do that, you can add a select input with variables as options.

Change site.R to this:

page_navbar("Site Title")
input_select("X Variable:", "variables", default = "x", id = "selected_x")
output_plot("selected_x", "y", "z")

Then rebuild:

site_build(output, open_after = TRUE, serve = TRUE)

Add structure

page_section is the main way to arrange components of the site, which can be wrapped around any set of input or output elements.

page_menu can be a nice way to arrange inputs.

These can be added to the previous example like this:

page_navbar("Site Title")
page_menu(
  input_select("X Variable:", "variables", default = "x", id = "selected_x"),
  default_open = TRUE
)
page_section(
  wraps = "col",
  output_plot("selected_x", "y", "z")
)

Add interactions

Plots (as well as maps) can be the source of mouse events (such as hovers and clicks). Information panes can respond to these events by displaying additional information.

For example, we can tie a tooltip-like output to the plot like this:

page_navbar("Site Title")
page_menu(
  input_select("X Variable:", "variables", default = "x", id = "selected_x"),
  default_open = TRUE
)
# give the plot an ID
output_plot("selected_x", "y", "z", id = "main_plot")
# then make an information output that subscribes to it
output_info("features.name", c(
  "variables.short_name" = "value"
), subto = "main_plot", floating = TRUE)

In output_info, features., variables., and data. refer to aspects of the hovered-over entity. variables. and data. also implicitly refer to a particular variable – by default, this will be the variable used for color, but setting the variable argument can change that (e.g., variable = "x" or variable = "selected_x").

You can also add floating = TRUE to make the output pane more like a tooltip.

Add variable information

The information output can also display additional information about the variables, which you can fill in when you add the data.

For example, run the same data_add command as before, but include some information about one of the variables:

data_add(
  "../../data.csv",
  list(
    variables = list(
      z = list(
        long_name = "Variable Z",
        description = "A random variable, drawn from a normal distribution.",
        statement = "{features.name} has a Z value of {value}"
      )
    )
  ),
  dir = paste0(output, "/docs/data")
)

Then, you can draw from that in the information output in site.R:

page_navbar("Site Title")
page_menu(
  input_select("X Variable:", "variables", default = "x", id = "selected_x"),
  default_open = TRUE
)
output_plot("selected_x", "y", "z", id = "main_plot")
output_info("features.name", c(
  "variables.long_name" = "value",
  "variables.description",
  "variables.statement"
), subto = "main_plot", floating = TRUE)

Add a Map

Maps will generally require shapes to be added from a separate, GeoJSON file. You can use the download_census_shapes function from the catchment package to download shapes for Census regions within the United States.

For example, we might download the shapes of states:

# remotes::install_github("uva-bi-sdad/catchment")
library(catchment)

# save the state shapes to the distribution directory
download_census_shapes(paste0(output, "/docs"), name = "states")

Then add a map to site.R (also subscribing the info pane to it):

page_navbar("Site Title")
page_menu(
  input_select("X Variable:", "variables", default = "x", id = "selected_x"),
  default_open = TRUE
)
output_plot("selected_x", "y", "z", id = "main_plot")
output_info("features.name", c(
  "variables.long_name" = "value",
  "variables.description",
  "variables.statement"
), subto = c("main_plot", "main_map"), floating = TRUE)
output_map(
  list(
    name = "data",
    id_property = "GEOID",
    url = paste0(output, "/docs/states.geojson")
  ),
  color = "z", id = "main_map"
)

Because the shapes also had some properties, these were added as entity features, giving some names.

Here, shapes were loaded in from a local file as part of the build process, but this same file could also be served and referred to by URL, in which case it would be loaded in separately. Loading the map shapes separately means the shapes can be independently cached by the browser, which can improve load times between sites that use the same make.

Add Entity Metadata

The map shapes file added some additional information about entities, such as their name, but this type of information can be added more directly through the data_add function’s meta argument. We’ve already used this argument to add variable metadata with a list in the variables entry. Similarly, entity metadata can be added in an ids entry.

For example, you might add names to some of the entries for which there is no state:

# include the ids list in your call to `data_add`
data_add(
  "../../data.csv",
  list(
    variables = list(
      z = list(
        long_name = "Variable Z",
        description = "A random variable, drawn from a normal distribution.",
        statement = "{features.name} has a Z value of {value}"
      )
    ),
    ids = list(
      variable = "ID",
      map= list(
        "61" = list(name = "No State 61"),
        "43" = list(name = "No State 43")
      )
    )
  ),
  dir = paste0(output, "/docs/data")
)

# then rebuild
site_build(output, open_after = TRUE, serve = TRUE)

Now you should see names for entities 61 and 43.

The ids field might be particularly useful if you already have metadata like this in a separate file, or plan to use that information between sites. In that case, you can replace the list in map with the path to a local file, or a URL to be loaded in dynamically.