RF-Generator co-author setup guide

A short guide for running the RF Generator on your own machine so you can test it and give feedback. Takes 20–30 minutes the first time; a couple of minutes thereafter.

You do NOT need: - A Vibrant Planet account - AWS credentials of any kind - Prior Shiny or git experience

You DO need: - A Mac, Windows, or Linux machine with ~4GB free RAM - An internet connection (the app pulls data from a public S3 bucket on each run) - About 20 minutes of setup time

1. Install R and RStudio

If you already have both, skip ahead to step 2.

Open RStudio to confirm it launches.

2. Install system libraries (Mac and Linux only)

The app uses the sf R package for spatial data, which needs a few system libraries. Windows users can skip this step — sf bundles these on Windows.

Mac (with Homebrew):

brew install gdal proj geos

If you don’t have Homebrew, install it from https://brew.sh first.

Linux (Ubuntu/Debian):

sudo apt install libgdal-dev libproj-dev libgeos-dev libudunits2-dev

3. Clone the repository

In a terminal:

git clone https://github.com/Vibrant-Planet-Open-Science/shiny-rf-generator.git
cd shiny-rf-generator

If you don’t use git, you can also download a ZIP from the repo’s green “Code” button on GitHub and unzip it.

4. Install R packages

Open shiny-rf-generator.Rproj in RStudio (double-click it in the Files pane). This sets RStudio’s working directory to the repo root.

Then paste this into the RStudio Console and press Enter:

install.packages(c(
  "shiny", "bslib", "leaflet", "sf", "dplyr", "tibble", "tidyr",
  "purrr", "DT", "plotly", "aws.s3", "here"
))

Installation takes 10–30 minutes the first time, mostly because sf and plotly are large. Subsequent runs are instant. If you see prompts about compiling from source, typing “no” and installing the binary is faster.

5. Run the app

In the RStudio Console:

shiny::runApp("R")

A browser window should open with the app at http://127.0.0.1:XXXX. The first load takes ~30 seconds while it downloads a small lookup file from S3.

6. Walk through the wizard

The app is an 8-step wizard. To test the full flow:

  1. AOI — either upload a .gpkg boundary file, or click ecoregion polygons on the map (try clicking one or two mid-sized ones in Colorado or the Sierras)
  2. Filters — leave empty to include everything
  3. Review — confirm stand count, click “Looks good — load data” (takes 1–2 minutes the first time; it’s pulling ~750MB from S3)
  4. RF type — pick “Stand / habitat characteristics”
  5. ECs — pick 2–3 components (e.g. canopy cover, basal area, surface shrub cover)
  6. Weights — accept defaults
  7. Click “Compute RFs”
  8. Download — see the resulting plots and tables

Giving feedback

A few things to note as you go through:

  • What’s confusing? Wording, button labels, step order — anything that makes you pause
  • What’s missing? ECs, treatments, scenarios that should be there but aren’t
  • What’s wrong? Anything that doesn’t match how you’d think about building an RF
  • Error messages — screenshots are great if something breaks

Send feedback however is easiest — slack, email, text, a shared doc — whatever works for you. If you’re comfortable filing GitHub issues, that’s also welcome but not required.

Troubleshooting

The app window is blank or shows an error page. Check the RStudio Console for error messages and send them to Kat. Most common cause: a package failed to install cleanly — try re-running the install.packages() line.

“Package ‘sf’ failed to load” on Mac. You likely missed the Homebrew step. Run brew install gdal proj geos and then reinstall sf: install.packages("sf").

The map doesn’t show ecoregion polygons. Check that the repo has a www/ecoregions_western.geojson file (size ~1–2MB). If missing, pull the latest from git.

“Could not connect to S3” or long hangs on startup. Check your internet connection. The public bucket sometimes has brief hiccups; wait a minute and try again.

Stand data loading is very slow. The ALL stand-level file is ~750MB and the first download takes a few minutes on slower connections. Subsequent runs use the cached version.

Getting help

If you get stuck for more than 15 minutes on setup, ping Kat directly — she’d rather hop on a quick Zoom than have you give up. The point is the manuscript feedback, not the installation experience.