Step 1 - Log in to RStudio Server

Open your web browser and go to the RStudio Server URL your instructor gave you. Log in with your username and password. You should see the RStudio interface with a Console pane on the left.

Step 2 - Create a folder and upload the zip file

1. In the Files pane (bottom right), click the Home icon (the little house)
2. Click New Folder and name it exactly regional_climate_narratives (all lowercase, with underscores), then click OK
3. Click the regional_climate_narratives folder to open it
4. Click the Upload button (it has an upward arrow icon)
5. Click Choose File, select Regional_Climate_Narratives--Student_Files.zip from your computer, and click OK

RStudio Server automatically unzips the file for you, so the files land directly inside regional_climate_narratives.

Step 3 - Point R at that folder

In the Console (bottom left pane), type:

setwd("~/regional_climate_narratives")

Then verify the installer file is there:

file.exists("Regional_Climate_Narratives_0.3.1.tar.gz")

This must print TRUE. If it prints FALSE:

• Did you upload the zip? (Go back to Step 2.)
• Are the files inside regional_climate_narratives? Check the Files pane (see the Step 2 check).
• Did you type the setwd(...) line exactly, including underscores? Run getwd() to see where R is looking.

Step 4 - Install the required packages (dependencies)

The package needs several other R packages to work. Install them first. Copy and paste this entire block into the Console and press Enter:

install.packages(c(
  "dplyr", "tidyr", "ggplot2", "lubridate",
  "sp", "sf", "gstat", "raster", "stars",
  "viridis", "maps", "mapdata", "patchwork"
))

This takes several minutes. You will see a lot of text scrolling by; that is normal. Wait until you see the > prompt again before continuing.

Step 5 - Install the Regional Climate Narratives package

Now install the actual package. Type:

install.packages("Regional_Climate_Narratives_0.3.1.tar.gz", repos = NULL, type = "source")

Wait for it to finish. The last lines should include:

* DONE (RegionalClimateNarratives)

If you see ERROR or had non-zero exit status instead: Read the error message. It usually names a missing package. Go back to Step 4 and install that package, then try Step 5 again.

Step 6 - Verify it works

Load the package. Note the name here has no underscores: R package names cannot contain them, so the package is RegionalClimateNarratives even though the files use Regional_Climate_Narratives:

library(RegionalClimateNarratives)

You should see this startup message:

===========================================================
 Regional Climate Narratives v0.3.1
===========================================================
 Regional Climate Trends Analysis and Visualization
 Type ?RegionalClimateNarratives for help
===========================================================

If you see a !!! warning about missing packages instead, run check_dependencies(), then try library(RegionalClimateNarratives) again.

Step 7 - Initialize your project

initialize_project("XX")

Replace XX with your state code. For example:

initialize_project("CA")   # California
initialize_project("TX")   # Texas
initialize_project("NY")   # New York

What this does:

• Creates a project folder in your home directory (e.g., ~/Regional_Climate_Narratives_CA/)
• Creates Data/, Output/, and Figures/ subfolders inside it
• Downloads a list of available weather stations from NOAA
• Changes your working directory to the project folder (you do NOT need to call setwd() yourself)

You should see output ending with Setup Complete! and a count of potential stations.

Step 8 - Select stations

select_stations(n = 50)

This picks the 50 stations with the longest, most complete records in your state.

Step 9 - Download data from NOAA

download_stations()

Step 10 - Save data in efficient format

load_and_save_stations(cleanup = TRUE)

This converts the downloaded files into a single compressed file that loads much faster in the future. Setting cleanup = TRUE deletes the temporary files to save disk space.

Part 2 is done. Your data is saved to disk and ready for analysis.

What to do every time you open RStudio

When your R session ends (you log out, your session times out, or you restart R), all variables in memory are erased. Your files on disk are fine; they are saved permanently. But R needs to reload them.

library(RegionalClimateNarratives)
initialize_project("XX")     # your state code, e.g., "CA"
load_stations()

Step 11 - Calculate climate trends

trends <- process_all_stations()

This runs the full analysis: cleaning dates, converting units, calculating anomalies, and fitting trend lines. It takes a minute or two.

You may see messages like:

• "Station USC00045123: Normals period = 1971-2000" - This is normal. That station did not have enough data in the standard 1961-1990 baseline period, so the package used a different 30-year window. The station is still included.
• "Station USC00067890: Cannot compute normals... Skipping." - That station did not have enough data for any baseline period. It is excluded. A few skipped stations is expected.

Check the results:

cat("Stations analyzed:", nrow(trends), "\n")
summary(trends$annual_trend_TMAX)

Step 12 - Create spatial objects

create_spatial_objects(trends)

This converts your trend data into a spatial format that can be mapped.

Step 13 - Make heat maps

Annual maximum temperature trend:

map_tmax <- create_heatmap(
  trends_sp,
  trend_var = "annual_trend_TMAX",
  title = paste(my.state, "- Annual Maximum Temperature Trend"),
  subtitle = "Change in degrees C per 100 years",
  state = my.state,
  colors = "temp"
)
print(map_tmax)

Save it as a high-resolution image:

ggsave(paste0(figuresfolder, "TMAX_annual_", my.state, ".png"),
       map_tmax, width = 10, height = 8, dpi = 300)

The file saves into your Figures/ folder. Find it in the Files pane under ~/Regional_Climate_Narratives_XX/Figures/.

Annual minimum temperature trend:

map_tmin <- create_heatmap(
  trends_sp,
  trend_var = "annual_trend_TMIN",
  title = paste(my.state, "- Annual Minimum Temperature Trend"),
  subtitle = "Change in degrees C per 100 years",
  state = my.state,
  colors = "temp"
)
ggsave(paste0(figuresfolder, "TMIN_annual_", my.state, ".png"),
       map_tmin, width = 10, height = 8, dpi = 300)

Precipitation trend (uses a different color scheme):

map_prcp <- create_heatmap(
  trends_sp,
  trend_var = "annual_trend_PRCP",
  title = paste(my.state, "- Annual Precipitation Trend"),
  subtitle = "Change in mm per 100 years",
  state = my.state,
  colors = "precip"
)
ggsave(paste0(figuresfolder, "PRCP_annual_", my.state, ".png"),
       map_prcp, width = 10, height = 8, dpi = 300)

Step 14 - Seasonal comparison (4-panel map)

library(patchwork)

winter_map <- create_heatmap(trends_sp, "winter_trend_TMAX",
              "Winter (Dec-Feb)", state = my.state, resolution = 0.15) +
  theme(legend.position = "none")

spring_map <- create_heatmap(trends_sp, "spring_trend_TMAX",
              "Spring (Mar-May)", state = my.state, resolution = 0.15) +
  theme(legend.position = "none")

summer_map <- create_heatmap(trends_sp, "summer_trend_TMAX",
              "Summer (Jun-Aug)", state = my.state, resolution = 0.15) +
  theme(legend.position = "right")

fall_map <- create_heatmap(trends_sp, "fall_trend_TMAX",
            "Fall (Sep-Nov)", state = my.state, resolution = 0.15) +
  theme(legend.position = "none")

seasonal_panel <- (winter_map | spring_map) / (summer_map | fall_map) +
  plot_annotation(
    title = paste("Seasonal TMAX Trends -", my.state),
    subtitle = "Change in degrees C per 100 years by season"
  )

ggsave(paste0(figuresfolder, "Seasonal_TMAX_", my.state, ".png"),
       seasonal_panel, width = 12, height = 10, dpi = 300)

Quick-start template (after Parts 1 and 2 are done)

Copy this block, change the state code on line 2, and run it:

library(RegionalClimateNarratives)
initialize_project("CA")     # <-- CHANGE THIS TO YOUR STATE
load_stations()

trends <- process_all_stations()
create_spatial_objects(trends)

map <- create_heatmap(trends_sp, "annual_trend_TMAX",
       paste(my.state, "Annual TMAX Trend"), state = my.state)
print(map)
ggsave(paste0(figuresfolder, "TMAX_", my.state, ".png"),
       map, width = 10, height = 8, dpi = 300)

Available heat map variables

Replace TMAX with TMIN or PRCP for min temperature or precipitation versions.

What happens when you close RStudio

Getting help

?initialize_project          # Help for a specific function
?RegionalClimateNarratives           # Package overview
help(package = "RegionalClimateNarratives")   # List all functions

If you are stuck, show your instructor the exact error message. Copy the red text from the Console.

file.exists(...) returns FALSE in Step 3

The installer file is not in your current working directory. Check:

1. Did you upload the zip? (Part 1, Step 2)
2. Are the files inside regional_climate_narratives? Check the Files pane.
3. Did you run setwd("~/regional_climate_narratives")? Run getwd() to see where R is looking.

“there is no package called …”

A required package is missing. Install it:

install.packages("sf")   # replace with the package name from the error

Or install all dependencies at once (copy-paste from Part 1, Step 4). Or run the included installer script, which handles everything with pass/fail reporting:

setwd("~/regional_climate_narratives")
source("install_package.R")

“Run initialize_project() first!”

You need to run initialize_project("XX") at the start of every R session. This is the most common error. It just means you started a new session and forgot the setup lines.

“RData file not found”

Your data has not been downloaded yet, or the download did not finish. Go back to Part 2 (Steps 8-10).

“could not find function ‘process_all_stations’”

Either the package is not loaded, or an old version is installed. Try:

library(RegionalClimateNarratives)

If that does not help, reinstall:

setwd("~/regional_climate_narratives")
install.packages("Regional_Climate_Narratives_0.3.1.tar.gz", repos = NULL, type = "source")

Then go to Session > Restart R in the RStudio menu, and try library(RegionalClimateNarratives) again.

Download seems stuck

NOAA servers can be slow. For 50 stations, expect 10 to 30 minutes. If it stops with errors, run download_stations() again. It skips stations already downloaded.

Messages about normals periods

"Normals period = 1971-2000" is informational. The station is still analyzed. This is not an error.

Warning about skipped stations

"Cannot compute normals for TMAX. Skipping." means that station did not have enough data. A few skipped stations is expected.

Heat map looks odd

• Need at least 20 stations (50 is better)
• Try resolution = 0.15 for smaller states, resolution = 0.08 for large states
• Make sure trends_sp exists: run create_spatial_objects(trends)

Where are my files?

Run getwd() to see your current project folder. Your files are in Data/ (weather data), Figures/ (saved heat maps), and Output/ (analysis results). Or navigate in the Files pane (bottom right of RStudio).