Use of the RIO-FINDER and RAPID Applications

Reproducibility notes:
   - R version:        4.5.2
   - RStudio version:  2023.12.0.369

To ensure that the tool works directly download the R and RStudio versions above.

This repository contains two complementary tools:
RIO-FINDER – an interactive application for discovering and filtering U.S. stream monitoring sites by water-quality parameters and wildfire intersections.

RAPID – a script-based workflow for analyzing specific wildfire perimeters against cached stream basins and monitoring sites.
The tools are designed to work together but can also be run independently.

Quick Start
1. Open the file RIOFINDER.Rproj
2. Run 0PackageInstallandSetup.R (once)
3. Run 5PlottingAndSiteSelection.R to explore sites
4. Run 6RunSingleFireAnalysis_new.R with run_mode = "full"
5. Switch to run_mode = "fire_only" for additional fires

1. Before You Start
Software installation
1. Install R for your operating system:
	Windows: https://cran.r-project.org/bin/windows/base/
	macOS: https://cran.r-project.org/bin/macosx/
2. Install RStudio Desktop:
	https://posit.co/download/rstudio-desktop/
3. Download the repository from GitHub (link).

⚠ Important
Place the repository in a local folder (not OneDrive, Dropbox, etc.).
Do not rename folders or scripts inside the repository.

2. Initial Setup (Required Once)

1. Open the file RIOFINDER.Rproj
	This ensures the correct working directory.
2. Navigate to the Code/ folder.
3. Open the script:
	0PackageInstallandSetup.R
4. Run the entire script using:
	Ctrl + Shift + Enter
This installs and loads all required R packages.

3. RIO-FINDER Shiny Application
(Interactive Site Discovery)

Running the application
Open the script:
	5PlottingAndSiteSelection.R
Run the entire script:
	Ctrl + Shift + Enter
The interactive map will open in the RStudio Viewer panel.

Using the RIO-FINDER interface
Note: The RIO-FINDER basemap derives from Natural Earth

Selecting sites:
- Click a site to select / deselect it (selected sites appear with a blue outline)
- Click-drag to draw a bounding box and select multiple sites
- Use the parameter dropdown and click “Select all sites in layer”
- Click “Clear selection” to remove all selected sites
Toggling layers
- Use the checkbox list to toggle water-quality parameter layers
- Turning layers on/off does not affect selected sites
Saving selected sites
1. Select sites using any method above
2. Click “Download site-parameter CSV”
3. Choose a save location for the output Excel file

Stopping Script 5 (Shiny App) and the Browse[1]> prompt

When Script 5 runs, it launches a Shiny app. In the Console you’ll see something like:
	Listening on http://127.0.0.1:XXXX

If you click Stop in RStudio to end the app, R may sometimes drop into a debug/browser prompt that looks like:
	Browse[1]>
- This is not a problem with the analysis—it's just R/Shiny exiting mid-callback.

What to do
In the Console, type:
	c and press Enter (continue/exit), or press Esc.

If the prompt persists, reset error handling by running the following in the console and try again:
	options(error = NULL)

4. RAPID Application
(Fire-Specific Analysis)

Conceptual workflow (important!)

RAPID uses two run modes:
Full run – updates the national site list and basin cache (slow, required once per day or when data change)
Fire-only run – analyzes a new fire perimeter using existing caches (fast, repeatable)

⚠ Important! Running the full run requires many calls to the USGS API. This is a limit of 50 requests per IP per hour for current sites.
- It is not required, but advised to request an API token to increase this to 1000 requests per hour.
- The script is set up to delay the calls as not to hit the limit, but this will make the update take multiple hours.

To request a token:
1. Go to https://api.waterdata.usgs.gov/signup to request an API key
2. When you get your key, use the command to open the .Renviron file
	usethis::edit_r_environ()
   If it doesn't run due to not finding the function 'usethis' run the code below in the console and then retry
	install.packages("usethis", repos = "https://cloud.r-project.org", type = "binary")
3. Past the key as
	API_USGS_PAT = "my_super_secret_token"
4. Save and then restart R using
	Ctrl + Shift + F10
5. Rerun and make sure the calls to API start counting from ~1000
6. Don't share your key as anyone using your API key will count against the number of requests available to you

💡 Key idea:
Run the slow part once, then analyze as many fire perimeters as you want.

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

Running RAPID
1. Navigate to the Code/ folder
2. Open:
	6RunSingleFireAnalysis_new.R
3. Scroll to the USER INPUTS section near the top
Update the following fields:
| Input             | Description                                      |
| ----------------- | ------------------------------------------------ |
| `run_mode`        | "full" or "fire_only"                            |
| `burn_path`       | Path to the .shp file                            |
| `fire_tag`        | Short label for output files                     |
| `ignition_date`   | Fire ignition date (`YYYY-MM-DD`)                |
| `pct_threshold`   | Minimum percent of basin burned                  |
| `fire_name_query` | Fire name (if shapefile contains multiple fires) |
| `fire_name_field` | Optional field name for fire names (or `NULL`)   |

Recommended execution sequence
1. First run (slow)
	run_mode <- "full"
2. Run the entire script:
	Ctrl + Shift + Enter
3. Subsequent fires (fast)
	run_mode <- "fire_only"
4. Update burn_path, fire_tag, and ignition_date, then rerun:
	Ctrl + Shift + Enter

RAPID outputs
If intersections exist:
- An interactive map of:
	- Fire perimeter
	- Intersecting basins
	- Monitoring sites
- The map appears in the RStudio Viewer
- Functionality mirrors RIO-FINDER (layer toggles, popups)
Output files are saved automatically in the run folder, including:
- Excel / CSV tables of intersecting sites and parameters
- HTML interactive maps

5. Output Folder Structure
All outputs generated by RIO-FINDER and RAPID are written to the New_Run_Files/ directory.
This directory is organized into two distinct parts:
-Persistent caches (reused across runs and days)
-Run-specific outputs (organized by date)
This structure prevents unnecessary precomputation while keeping each analysis reproducible.

New_Run_Files/ overview
New_Run_Files/
├── cache_state/                # Persistent cache (DO NOT DELETE)
│   ├── 00_state/
│   │   ├── raindrop_trace_df.rds
│   │   ├── catchment_df_cache.rds
│   │   ├── catchment_list_final.rds
│   │   ├── missing_ids_after_raindrop_trace.rds
│   │   └── missing_ids_after_split_catch.rds
│   │
│   ├── 02_map_cache/
│   │   ├── all_basins_sf.qs
│   │   ├── missing_all_basins.qs
│   │   └── stale_in_qs_not_on_disk.qs
│   │
│   └── (optional)
│       ├── all_sites_latest.rds
│       ├── ts_meta_all_paramcd_latest.rds
│       └── ts_meta_all_latest.rds
│
├── run_YYYYMMDD/               # Outputs for a specific run date
│   ├── 00_state_snapshot/
│   │   ├── all_sites.rds
│   │   ├── ts_meta_all_paramcd.rds
│   │   └── ts_meta_all.rds
│   │
│   ├── 01_fire_valid/
│   │   ├── burn_perimeters_valid_.rds
│   │   └── burn_perimeters_valid_.gpkg
│   │
│   ├── 03_intersections/
│   │   ├── burn_basin_intersections__.csv
│   │   ├── burn_basin_intersections___filtered_pctXX.csv
│   │   └── burn_basin_intersections___filtered_pctXX.rds
│   │
│   └── 04_maps/
│       ├── FireFlow_param_map__.html
│       └── FireFlow_param_map__/   # leaflet assets
│
└── run_YYYYMMDD/
    └── ...
Explanation of key folders

cache_state/ (persistent – reused across runs)
This folder stores computationally expensive intermediate results that should not be regenerated every run.
Do not delete this folder unless you intend to rebuild everything.

- 00_state/
	- Results from raindrop tracing and split-catchment delineation
	- Used to ensure only new sites trigger basin processing
- 02_map_cache/
	- Cached basin geometries and audit files
	- Enables incremental basin downloads

These caches allow RAPID to:
- Re-run site discovery each time
- Only process new sites that were not previously analyzed

run_YYYYMMDD/ (run-specific outputs)
Each execution of RAPID creates a dated folder containing all outputs for that run.

This ensures:
- Results are reproducible
- Outputs from different days or fires are not overwritten

Contents include:
00_state_snapshot/
- Snapshot of site lists and metadata used in this run

01_fire_valid/
- Standardized and validated wildfire perimeter files

03_intersections/
- Basin × fire intersection results (raw + filtered)

04_maps/
- Interactive HTML maps with Leaflet assets

Which folders should users interact with?
| Folder                           | Purpose                        | User action            |
| -------------------------------- | ------------------------------ | ---------------------- |
| `cache_state/`                   | Persistent computational cache | Do not modify          |
| `run_YYYYMMDD/01_fire_valid/`    | Validated fire files           | Optional review        |
| `run_YYYYMMDD/03_intersections/` | CSV / RDS results              | Main analysis output   |
| `run_YYYYMMDD/04_maps/`          | Interactive maps               | Open in browser        |