Use of the RIO-FINDER and RAPID Applications

Reproducibility Notes

• R version: 4.5.2
• RStudio version: 2023.12.0.369

For native execution, install the versions above.

This repository contains two complementary tools:

• RIO-FINDER: interactive application for discovering/filtering U.S. stream monitoring sites by water-quality parameters and wildfire intersections (RIOFINDER_2026/Code/5RIOFINDERPlottingAndSiteSelection.R).
• RAPID: script-based workflow for analyzing wildfire perimeters against cached stream basins and monitoring sites (RIOFINDER_2026/Code/6RAPIDAnalysis.R).

These tools can be used together or independently.

1) Setup Options

Option A (Recommended): Docker

Docker is recommended for reproducibility and avoiding host-specific package/compiler issues.

A1. Prerequisites

1. Install Docker Desktop: https://www.docker.com/
2. Use AMD64 installer for standard desktop/server processors.
3. Open Docker Desktop and confirm it is running.

A2. Open terminal in repository root (lower right corner)

In PowerShell, go to your repository root by replacing the folder path below (folder containing riofinder_image.tar and Code/):

powershell cd C:\Users\jdoe\Documents\RIOFINDER_2026

A3. Load image tar

powershell docker load -i riofinder_image.tar

Expected image: jacgonzalez24042/riofinder:reviewer-v1

A4. (Optional but strongly recommended for RAPID full mode) Set USGS API key on host

powershell $env:API_USGS_PAT="your_token_here"

A5. Run container

powershell docker run --rm -it --platform linux/amd64 -p 3838:3838 ` --memory=12g --memory-swap=12g ` -e API_USGS_PAT="$env:API_USGS_PAT" ` --mount "type=bind,source=$($PWD.Path),target=/home/rstudio/RIOFINDER" ` --mount "type=volume,source=riofinder_renv,target=/home/rstudio/RIOFINDER/renv/library" ` jacgonzalez24042/riofinder:reviewer-v1 /bin/bash

A6. First run only (per new riofinder_renv volume)

Inside container:

bash Rscript -e "renv::restore(prompt = FALSE)"

A7. Verify API key is visible inside container (for RAPID full mode)

Inside container:

bash Rscript -e "cat('Using API key:', nzchar(Sys.getenv('API_USGS_PAT')), '\n')"

Expected: Using API key: TRUE

Option B: Native R + RStudio (Fallback)

Use native setup if Docker is unavailable.

1. Install R 4.5.2:
2. Windows: https://cran.r-project.org/bin/windows/base/old/
3. macOS: https://cran.r-project.org/bin/macosx/
4. Install RStudio Desktop: https://posit.co/download/rstudio-desktop/
5. Download repository from HydroShare: http://www.hydroshare.org/resource/81a7609e5a514b45aefcba032136e79c
6. Open RIOFINDER.Rproj
7. Run RIOFINDER_2026/Code/0PackageInstallAndSetup.R once.

Important: - Keep repository in a local folder (not OneDrive/Dropbox/network sync folders). - Do not rename repository folders/scripts unless paths are updated.

2) Required External Data (MTBS)

If updating perimeter processing/intersection workflows, download MTBS perimeter data.

• Source: https://www.mtbs.gov/direct-download
• Format: ESRI shapefile (.shp + .shx + .dbf + .prj)
• Expected path:

RIOFINDER_2026/Ext_Data_Download/mtbs_perimeter_data/mtbs_perims_DD.shp

If stored elsewhere, update script paths.

3) Full Pipeline Script Order

Run scripts in this order for full workflow:

1. Code/0PackageInstallAndSetup.R
2. Code/1StreamSiteIndentification.R
3. Code/2StreamBasinDownload.R
4. Code/3ProcessBasinAndFireShapefiles.R
5. Code/4BasinAndFireIntersectionAnalysis.R
6. Code/5RIOFINDERPlottingAndSiteSelection.R
7. Code/6RAPIDAnalysis.R

4) Run RIO-FINDER Interactive Map (Script 5)

Docker

Inside container:

bash R -e "options(shiny.host='0.0.0.0', shiny.port=3838, shiny.launch.browser=FALSE); source('Code/5RIOFINDERPlottingAndSiteSelection.R')"

Open on host browser:

http://localhost:3838

Native RStudio

1. Open RIOFINDER_2026/Code/5RIOFINDERPlottingAndSiteSelection.R
2. Run full script (Ctrl + Shift + Enter)
3. Open URL shown in console (typically http://127.0.0.1:XXXX)

5) Run RAPID (Script 6)

RAPID is configured by editing user inputs in the script, then running the full script.

Run modes

• run_mode <- "full": refresh national site list + basin caches (slow; first run)
• run_mode <- "fire_only": reuse cache for additional fires (fast)

API rate-limit note

Without API key, full mode may be very slow (50 req/hr baseline).
With API key, calls are faster (target up to ~1000 req/hr in script settings).

Sign up: https://api.waterdata.usgs.gov/signup

Preparing fire perimeter data:

1. Download a wildfire perimeter shapefile
2. Unzip the folder
3. Place the folder inside: RIOFINDER_2026/Ext_Data_Download/
4. Ensure the .shp file is inside the folder (not nested further)

Native API key setup

In R console:

r usethis::edit_r_environ()

Add line:

text API_USGS_PAT="my_super_secret_token"

Restart R (Ctrl + Shift + F10).

Install "usethis" if needed r install.packages("usethis", repos = "https://cloud.r-project.org", type = "binary")

Script 6 user input fields

Open RIOFINDER_2026/Code/6RAPIDAnalysis.R and update:

Run Script 6

Docker

Inside container:

bash Rscript Code/6RAPIDAnalysis.R

Native

Run full script in RStudio (Ctrl + Shift + Enter).

Recommended sequence

1. First run: run_mode <- "full"
2. Additional fires: run_mode <- "fire_only" + update fire-specific fields

6) Output Structure

All outputs are written under New_Run_Files/.

• New_Run_Files/cache_state/: persistent cache (reused across runs)
• New_Run_Files/run_YYYYMMDD/: date-stamped run outputs

Typical outputs:

• Validated fire perimeters
• Basin × fire intersection tables (csv, rds)
• Interactive RAPID map widget HTML

7) Troubleshooting

• docker: command not found

• Install Docker Desktop and restart terminal.

• no match for platform in manifest

• On Apple Silicon use --platform linux/amd64.

• Missing packages in container after mount (e.g., there is no package called 'DT')

• Use named volume mount for renv/library.

• Run Rscript -e "renv::restore(prompt = FALSE)" in container.

• sh: 1: xdg-open: not found

• Expected in headless container; open browser URL manually.

• st_union assumes planar warnings

• Non-fatal sf warning for lon/lat operations.

• Using API key? FALSE in Script 6 logs

• Key was not passed into container.
• Start container with: -e API_USGS_PAT="$env:API_USGS_PAT"

• Verify with: Rscript -e "cat(nzchar(Sys.getenv('API_USGS_PAT')), '\n')"

• HTTP 429 Too Many Requests in Script 6 full mode

• API throttling. Use API key and rerun (script resumes from checkpoints).

• Script ends with Killed

• Usually Docker memory limit (OOM). Increase Docker memory by closing the container and use the following commands to increase the memory before repeating the setup above.

• Increase memory with: ```powershell $wslConfig = @" [wsl2] memory=12GB processors=8 swap=8GB "@

  $wslConfig | Set-Content -Path "$env:USERPROFILE.wslconfig" - Restart docker with:powershell wsl --shutdown - Verify memory increase with:powershell Get-Content "$env:USERPROFILE.wslconfig" ```

• Error: object 'wd' not found in Code/1StreamSiteIndentification.R

• Temporary workaround: bash Rscript -e "wd <- file.path(getwd(), 'Code'); source('Code/1StreamSiteIndentification.R')"