Lesson_Plan_Advanced.Rmd

---
title: "Lesson Plan Advanced"
author: "Natural Resources Department"
date: "`r Sys.Date()`"
output: 
  html_document:
    theme: darkly
    css: styles.css
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, warning = FALSE, message = FALSE)

library(dplyr)
library(readxl)
library(tidyr)
library(lubridate)

cleaned <- read.csv("cleaned.csv")
```

## 1) Spatial data wrangling

### 1.1) sf

`sf` is a fantastic package that lets you work with spatial data (polygons, points, and lines) in R via a *spatial data frame*. A spatial data frame is just a regular data frame plus a special column that stores geometry and some spatial metadata. Spatial DFs will always have a geometry list-column of class `sfc_`, which holds the points/polygons/etc, a coordinate reference system (for you it should almost always be *WGS84* or *NAD83*), and a bounding box value that defines the whole area.

Spatial data can be manipulated in many similar ways to normal data.frames, but they also have some special methods that understand space and geometry. Let's cover a few now!

#### 1.1.1) `st_read()`

This is going to be your 'intake' function; think of this just like read.csv or read_excel. One quirk with reading shapefiles is you need all of the supporting files - `.sbn`, `.sbx`, `.prj`, `.cpg`, etc. - but you only read in the `.shp` file. For example:

```{r load-sf}
#install.packages("sf")
library(sf)
points <- st_read("shapefiles/sampling_points.shp")
```

We can begin to explore this new spatial data by using st_bbox:

```{r inspect-bbox}
st_bbox(points)
```

This prints the minimum and maximum x and y values as UTM coordinates. We can also get a vector of the x, y, and z coordinates with `st_coordinates()`:

```{r inspect-coords}
st_coordinates(points$geometry)
```

Perhaps more important, however, is gleaning what CRS your data is in:

```{r inspect-crs}
st_crs(points)
```

Our data is in NAD83 - this makes sense for the UTM zone we are in, but for plotting, you should always have your data in WGS84. WGS84 uses latitude and longitude, which leaflet likes a lot better.

#### 1.1.2) `st_transform()`

If you ever want to change the CRS of your spatial data, an important function to know is `st_transform()`.

It's a very simple function, it just takes an sf dataframe and an EPSG code

```{r transform-points}
points_transformed <- st_transform(points, crs = 4326)

st_crs(points_transformed)
st_coordinates(points_transformed)
```

EPSG codes are just numeric strings used to represent different coordinate systems. NAD83 Zone 15N is `26915`, WGS84 is `4326`. You likely wouldn't ever need to use any others.

You can see after the st_transform that we're now using the "World Geodetic System 1984 ensemble" and we got latitude and longitude values from `st_coordinates()`. How fancy :)

### 1.2) leaflet

leaflet is a fantastic package for visualizing spatial data. It has a ton of basemap options and powerful ways to plot spatial data in R.

You can actually plot spatial data normally:

```{r base-plot-points}
plot(points)
```

But it looks pretty horrible, and you can't tell where anything is! Leaflet has a much better solution:

#### 1.2.1) `addMarkers()`

```{r leaflet-markers}
#install.packages("leaflet")
library(leaflet)

# Try switching points_transformed with points to see the difference in coordinate systems.
leaf <- leaflet(data = points_transformed) %>%
  addProviderTiles("Esri.WorldImagery") %>%   # This is your basemap. This string is the regular imagery basemap from Esri
  addMarkers(label = points_transformed$Site) # For whatever reason, you need to use atomic notation
                                              # to refer to columns in piped leaflet functions
# view the map                                          
leaf
```

Try replacing points_transformed with points to see the difference having your data in WGS84 makes. One looks a lot better than the other!

#### 1.2.2) `addPolygons()`

We can plot polygons with leaflet too:

```{r load-polygons}
# load in the shapefile
polygons <- st_read("shapefiles/tribal_wetlands.shp")
# transform to WGS84
polygons <- st_transform(polygons, crs = 4326)
```

```{r leaflet-polygons}
leaf2 <- leaflet(data = polygons) %>%
  addProviderTiles("Esri.WorldImagery") %>%
  addPolygons(      
    color = "black",    # border color
    fillColor = "cyan", 
    opacity = 0.8,      # opacity of the border
    fillOpacity = 0.7,  
    weight = 0.5        # thickness of border line
  ) #%>%
  #addMarkers(data = points_transformed,
  #           label = points_transformed$Site)

# view the map
leaf2
```

This function isn't much different from `addMarkers()` - though you may want to do more styling like we did here. You can have multiple layers on a map by simply piping in another "Control" (layer). Try it out by un-commenting the `addMarkers()` call.

You can also map lines or really any data with an X and Y.

#### 1.2.3) `addMinicharts()`

One of my favorite things to do with leaflet is minicharts. Its a great, albeit finicky way to visualize numeric spatial data.

Maybe we're curious about the average proportion of nitrogen species at the sample sites. Let's dive in:

```{r leaflet-minicharts}
# install.packages("leaflet.minicharts")
library(leaflet.minicharts)

# Minicharts are finicky! They require the data to be in a very specific format: 
# - One row per location (per chart) 
# - One column per "slice" (for pie charts, that means each slice is a separate column) 
# - Separate numeric columns for latitude and longitude 

# Build lookup table of site + lat + lng from sf points
latlng <- points_transformed %>%
  rename(site = Site) %>%  # Match 'site' name used in 'cleaned' / 'nitrogen'
  mutate(
    lng = st_coordinates(geometry)[, 1],  # X = longitude
    lat = st_coordinates(geometry)[, 2]   # Y = latitude
  ) %>%
  st_drop_geometry() %>%                  # leaflet.minicharts wants plain numbers, not sf
  select(site, lat, lng)

# Summarise nitrogen species at each site
# Use the mean across all dates to get a "typical" composition per site
nitrogen <- cleaned %>%
  group_by(site) %>%
  summarise(
    Ammonia = mean(nitrogen_ammonia, na.rm = TRUE),
    NOx     = mean(nitrogen_no2_plus_no3, na.rm = TRUE),
    # Organic N ≈ TKN - ammonia (TKN = organic N + ammonia N)
    Organic = mean(nitrogen_kjeldahl_total - nitrogen_ammonia, na.rm = TRUE)
  ) %>%
  # Replace all-NA summaries with 0 so pies still render
  mutate(across(c(Ammonia, Organic, NOx), ~ replace_na(., 0))) %>%
  # Attach lat / lng for each site
  left_join(latlng, by = "site")

# Extract nitrogen columns as a matrix for leaflet.minicharts
pie_mat <- as.matrix(nitrogen[, c("Ammonia", "Organic", "NOx")])
# Rows = sites (same order as 'nitrogen'); columns = N species

# Add pie minicharts to an existing leaflet map (leaf2)
leaf3 <- leaf2 %>%
  addMinicharts(
    lng       = nitrogen$lng,
    lat       = nitrogen$lat,
    chartdata = pie_mat,
    type      = "pie",
    width     = 40,
    height    = 40,
    legend    = TRUE   # Uses column names of 'chartdata'
  )

leaf3

```

#### 1.2.4) Popups and HTML

One final topic to tackle before we move on is creating popups with leaflet maps. Leaflet was originally created for JavaScript and adapted into many other languages, including R. A consequence of this is some other language bits remain; one of them being popups and HTML.

Popups are little text cards that appear when you click on a control (a layer - polygons, points, minicharts, etc). The text on these cards must be defined using HTML syntax. You build these popups by passing a character vector of HTML strings, one per site, to a `popup =` argument. You can keep it simple with plain text, or use basic HTML tags like `<b>` (bold), `<br>` (break or newline), and `<u>` (underline) to make the content easier to scan.

With html just remember; any time you use a tag like `<TAG>`, you must escape it when you want the effect to stop with `</TAG>`; this is true for most HTML tags (`<br>` would be an exception as it indicates the end of a line). You will see this demonstrated in the chunk below.

Let's rebuild the polygon map with popups:

```{r}
# You need a unique tag for each polygon
# We'll create a new character column directly in the data.frame:
polygons <- polygons %>%
  mutate(
    popup = paste0(
      "<b>Class: </b>", WETLAND_CL, "<br>", # <b> creates bold text
      "<b>Acres:</b> ", ACRES, "<br>", # <br> creates a line break
      "<b><i>Unique Id:</i></b><u> ", UniqueID, "</u>" # <i> for italics, <u> for underline
    )  # You can combine tags too!
  )

# Now pass that new column to the popup argument in addPolygons
leaf4 <- leaflet(data = polygons) %>%
  addProviderTiles("Esri.WorldImagery") %>%
  addPolygons(      
    color = "black",    # border color
    fillColor = "cyan", 
    opacity = 0.8,      # opacity of the border
    fillOpacity = 0.7,  
    weight = 0.5,        # thickness of border line
    popup = polygons$popup
  )

leaf4
```

Creating popups is not terribly difficult, but I always struggle to remember those html tags. Google is your friend!

## 2) Code reproducibility

So far, everything we’ve done has lived in this single R Markdown file. That’s great for a small lesson, but in real projects you’ll often have a lot of repeated code: the same summary, the same plot structure, the same cleaning steps, just with a different site, date range, or parameter. This is where reproducibility and functions really start to shine.

A reproducible workflow usually has three ingredients:

-   Your raw data (CSV, shapefile, etc.)
-   Your code (scripts, functions, Rmds)
-   Your environment (which packages you used, and sometimes which versions)

R Markdown helps bundle code + narrative, but functions help make that code modular and re-usable.

### 2.1) Writing functions

A function is just a reusable block of code. Instead of copying and pasting the same five lines over and over, you can wrap them in a function and call it with different inputs. The basic structure of a function is:

``` r
name_of_function <- function(argument1, argument2, ...) {
  # do stuff with the arguments
  result <- ... # some code that creates an output
  return(result)
}
```

Let’s write a small function that does something we’ve already done manually: summarise the average temperature and conductivity at a single site.

```{r summarise-site-function}
summarise_site <- function(data, site_name) {
  data %>%
    filter(site == site_name) %>%                # keep only rows for the chosen site
    summarise(
      avg_temp   = mean(temp,    na.rm = TRUE),  # average temperature
      avg_spcond = mean(sp_cond, na.rm = TRUE)   # average specific conductivity
    )
}
```

In our environment, `summarise_site` is just an object like any other, but it happens to be of class "function".

The function takes two *arguments*: `data` (a data frame like `cleaned`) and `site_name` (a character string like `"Mystic Lake Center"`). Inside the function, we use `data` instead of a specific data frame name so it’s flexible; we can pass any compatible data frame.

The last expression in the function (here, the result of `summarise(...)`) is returned automatically, even if we don’t explicitly write `return()`.

We can now use this function for any site without rewriting the logic:

```{r summarise-site-demo}
summarise_site(cleaned, "Mystic Lake Center")

summarise_site(cleaned, "Arctic Inflow 3")
```

You should see a tiny data frame with two columns (`avg_temp`, `avg_spcond`) and one row for each call.

You can make functions as small or as large as you like, but a good rule of thumb is: one function should do *one* clear thing (e.g., “clean dates”, “summarise by site”, “make this plot”).

### 2.2) Function use cases

When should you bother writing a function instead of just copy-pasting code?

Here are a few common use cases:

1.  **You’re repeating yourself.**\
    If you find yourself doing the same transformation with only small tweaks (e.g., changing the site name, date range, or analyte), it’s a great candidate for a function.

For example, you could wrap part of your chemistry cleaning pipeline:

```{r clean-chemistry-function}
clean_chemistry <- function(path) {
  read_excel(path, col_types = c("text", "text", "numeric", "text", "date", "text", "text",
                                 "numeric", "numeric", "numeric", "text", "text", "numeric", "text")) %>%
    mutate(
      Date = format(SampleDateTime, "%d/%m/%Y"),
      Date = dmy(Date)
    )
}
```

Then you can call:

```{r clean-chemistry-call}
chemistry_clean <- clean_chemistry("chemistry.xlsx")
```

2.  **You want easier debugging.**\
    It’s often easier to debug one small, well-defined function than a huge script. You can test functions with simple calls and check that they behave as expected.

3.  **You want to re-use code across projects.**\
    Once a function is stable and useful, you can put it in a separate `.R` script (often in a folder called `R/`) and source it into multiple Rmds. Eventually, you can bundle these helper functions into an R package so you can install and load them with `library()` like any other package.

## 3) Shiny

Before we start building Shiny apps, it’s helpful to understand why the skills from the last section matter so much. A Shiny app is essentially a giant function. Every line of code can be re-run constantly in response to user input, so messy or fragile code becomes much harder to debug and repeated copy-and-paste code becomes painfully slow. Functions that encapsulate logic become incredibly valuable because Shiny will reuse them over and over.

In other words: Shiny rewards clean, reusable, modular R code, and it punishes everything else. With that foundation, here’s how Shiny itself works.

A Shiny app has two major components:

1.  The UI (User Interface): what the user sees
    -   buttons, dropdowns, maps, plots, tables, etc.
2.  The server function: your logic
    -   how data is filtered, which reactive expressions update, what plots/maps to redraw, and what happens when the user interacts with the interface.

Shiny connects these pieces using shinyApp(ui, server). As the user interacts with the UI, the server continually re-runs the appropriate code, updating outputs automatically. In this section we’ll build a minimal Shiny app that displays a map with your wetland polygons (polygons), overlays your monitoring points (points_transformed) and shows a popup with site-level summary values when a point is clicked.

The simplest possible shiny app might look like:

```{r simple-shiny}
#install.packages("shiny")
library(shiny)

ui <- fluidPage(
  "Hello World!"
)
server <- function(input, output, session){
  
}
```

Then run:

```{r simple-shiny-2}
shinyApp(ui, server)
```

That's a (technically) complete shiny app! Notice how the server is just an empty function; the server's only job is to describe the behavior of the UI elements. Since the only UI element we have is static text, we don't need any logic describing it.

Let's consider a slightly more complicated example:

```{r table-shiny}
#install.packages("DT")
library(DT)
data <- cleaned

ui <- fluidPage(
  dataTableOutput("table")
)
server <- function(input, output, session){
  output$table <- renderDataTable({
    datatable(data)
  })
}
```

```{r table-shiny-2}
shinyApp(ui, server)
```

Here, we create a ui data table output with `dataTableOutput()`, so our server needs a corresponding `renderDataTable` call. In the next section, we'll build a UI object with a `leafletOutput()` so we can start to make an app with maps!

### 3.1) UI

The UI (User Interface) is the part of a Shiny app that the user interacts with. But it’s also important to understand how UI code is structured and how it connects to what the server does.

Shiny UI code is written using R functions that generate HTML. For example, `fluidPage()`, `sidebarLayout()`, `selectInput()`, and `leafletOutput()` are all R functions that build the web page behind the scenes. You’re not writing HTML directly; Shiny writes it for you based on the UI functions you call.

A common and simple layout is:

-   `fluidPage()` as the overall container

-   A `sidebarLayout()` with:

    -   `sidebarPanel()` on the left (for inputs)

    -   `mainPanel()` on the right (for outputs)

Even though the UI looks like a static description of a web page, each UI element has a name (its input/output ID) that the server uses. An input element like `selectInput("site", ...)` creates `input$site` on the server. An output element like `leafletOutput("map")` expects the server to fill in `output$map`.

This ID-based link is how Shiny connects the two halves of the app; you declare inputs and outputs in the UI, and you build the logic for those inputs/outputs in the server.

Let's make a goal of building an app that houses some of the leaflet maps we made. Here, we'll tackle the UI definition:

```{r shiny-ui}
# First, create a small summary table for each site that we'll use for popups
site_summary <- cleaned %>%
  group_by(site) %>%
  summarise(
    avg_temp   = mean(temp,    na.rm = TRUE),
    avg_spcond = mean(sp_cond, na.rm = TRUE)
  ) %>%
  # Join with lat/lng so we can plot the sites
  left_join(latlng, by = "site")

# You can think of UI definition like a russian nesting doll
# Everything lives inside fluidPage, and you will have subsections
ui <- fluidPage(
  titlePanel("Wetland Monitoring Map"),
  sidebarLayout(
    sidebarPanel(
      helpText("Click on a monitoring point to see average values for that site.")
    ),
    mainPanel(
      leafletOutput("map", height = 500)  # Placeholder for our interactive map
    )
  )
)
```

The important part here is `leafletOutput("map")`. This tells Shiny: “I’m going to create a leaflet map in the server called `output$map`, and I want to display it here.”

### 3.2) Server

The server function describes how inputs and outputs are connected. In the UI, we told Shiny where to display the leaflet map, but we still need to tell it how to render the leaflet map.

In Shiny, every output has a corresponding render function:

-   `leafletOutput()` in the UI pairs with `renderLeaflet()` in the server.
-   `plotOutput()` pairs with `renderPlot()`.
-   `tableOutput()` pairs with `renderTable()`, and so on.

Inside each output call, you will generally define the output object how you normally would; if you used `renderPlot()`, call `ggplot(...)`, `leaflet()` for `leafletOutput()`, etc. The only difference you will encounter is reactivity, but we will tackle that in the next section.

Let’s define a server function that starts a leaflet map with a basemap, adds the wetland polygons as a layer, adds monitoring points as circle markers, and uses a popup to show average temperature and conductivity when you click a point:

```{r shiny-server}
server <- function(input, output, session) {
  
  # Notice how similar this leaflet code is to what we were doing earlier
  # A lot of shiny is just having a good base knowledge in R, then learning which wrappers to use
  output$map <- renderLeaflet({ 
    leaflet() %>%
      addProviderTiles("Esri.WorldImagery") %>%
      # Polygon layer: wetland boundaries
      addPolygons(
        data       = polygons,
        color      = "black",
        fillColor  = "cyan",
        opacity    = 0.8,
        fillOpacity = 0.4,
        weight     = 0.7,
        group      = "Wetlands"
      ) %>%
      # Let's use circle markers so we can customize them!
      addCircleMarkers(
        data        = site_summary,
        lng         = ~lng,
        lat         = ~lat,
        radius      = 5,
        stroke      = TRUE,
        color = "orange",
        fillOpacity = 0.9,
        group       = "Stations",
        popup = ~paste0(
          "<strong>Site: </strong>", site, "<br>",
          "<strong>Average Temp (°C): </strong>", round(avg_temp, 1), "<br>",
          "<strong>Average SpCond (µS/cm): </strong>", round(avg_spcond, 1)
        )
      ) %>%
      # Optional: add a simple layer control so users can toggle polygons/points
      addLayersControl(
        overlayGroups = c("Wetlands", "Stations"),
        options = layersControlOptions(collapsed = FALSE)
      )
  })

}
```

Notice that we define the map exactly the same as before (`addProviderTiles`, `addPolygons`, etc.), but now it's all inside `renderLeaflet()`. `site_summary` already includes lat/lng columns and averages per site, thanks to the code we wrote earlier.

To actually run the app, you combine `ui` and `server` like this:

```{r run-shiny, eval=FALSE}
shinyApp(ui, server)
```

Run that chunk and a small window should pop up with your interactive map.

### 3.3) Reactivity

Reactivity is Shiny’s secret sauce. The basic idea:

-   **Inputs** (like sliders, dropdowns, text boxes, or even map clicks) are represented as `input$something`.
-   **Outputs** (like plots, tables, and maps) are defined as `output$something <- render...({ ... })`.
-   When an input value changes, any reactive code that *depends* on it is automatically re-run, and the outputs update.

In our current app, the map itself doesn’t have a user-controlled input yet; it just renders once. But we do have one form of interaction: clicking on a point to see a popup. Leaflet handles that for us in the browser. We told it what the popup should say, and it shows it when the user clicks the point.

To see reactivity more explicitly, let's add a dropdown that lets the user choose which site to highlight:

```{r shiny-ui-reactive}
ui <- fluidPage(
  titlePanel("Wetland Monitoring Map"),
  sidebarLayout(
    sidebarPanel(
      selectInput( # This is the important bit here
        "site_choice", # selectInput creates a dropdown selection box
        label = "Choose a site to highlight:", # Choices must be loaded from existing data
        choices = sort(unique(site_summary$site)), # You could also use `c(...)` notation for small lists.
        selected = sort(unique(site_summary$site))[1] # This line sets a 'default' choice
      ),
      helpText("Click on a monitoring point to see average values for that site.")
    ),
    mainPanel(
      leafletOutput("map", height = 500),
      br(),
      h4("Selected site summary"),
      tableOutput("site_table")  # <- new table output
    )
  )
)
```

And then, in the server, we could use `input$site_choice` to change the styling and the bounding box of the map:

```{r shiny-server-reactive}
server <- function(input, output, session) {

  # Reactive: filter down to just the selected site
  selected_site <- reactive({
    site_summary %>%
      dplyr::filter(site == input$site_choice)
  })

  output$map <- renderLeaflet({
    leaflet() %>%
      addProviderTiles("Esri.WorldImagery") %>%
      addPolygons(
        data        = polygons,
        color       = "black",
        fillColor   = "cyan",
        opacity     = 0.8,
        fillOpacity = 0.4,
        weight      = 0.7,
        group       = "Wetlands"
      ) %>%
      addCircleMarkers(
        data        = site_summary,
        lng         = ~lng,
        lat         = ~lat,
        radius      = ~ifelse(site == input$site_choice, 8, 5),  # reactively change radius
        color       = "orange",
        stroke      = TRUE,
        fillOpacity = 0.9,
        group       = "Stations",
        popup = ~paste0(
          "<strong>Site: </strong>", site, "<br>",
          "<strong>Average Temp (°C): </strong>", round(avg_temp, 1), "<br>",
          "<strong>Average SpCond (µS/cm): </strong>", round(avg_spcond, 1)
        )
      ) 
  })
  
  observeEvent(input$site_choice, {
    site_pt <- site_summary %>%
      dplyr::filter(site == input$site_choice)
  
    # require at least one matching row
    req(nrow(site_pt) > 0)
  
    # pick the first row (or compute a mean if you prefer)
    lng_center <- site_pt$lng[1]
    lat_center <- site_pt$lat[1]
  
    leafletProxy("map") %>%
      flyTo(
        lng  = lng_center,
        lat  = lat_center,
        zoom = 15  # optional; keeps current zoom if you omit
      )
  })

  # Table driven by the same input$site_choice
  output$site_table <- renderTable({
    selected_site() %>%
      dplyr::transmute(
        Site                      = site,
        `Average Temp (°C)`       = round(avg_temp, 1),
        `Average SpCond (µS/cm)`  = round(avg_spcond, 1)
      )
  })

}
```

Run the app again

```{r run-shiny-reactive, eval=FALSE}
shinyApp(ui, server)
```

`input$site_choice` is reactive. Whenever the user picks a different site from the dropdown, that value changes. Because `renderLeaflet()` depends on `input$site_choice` (we use it inside `ifelse(...)`), Shiny knows that the map needs to be re-run when the input changes. Shiny recomputes the map with the new radius values, and the selected site is highlighted.

You don’t have to manually re-run anything, Shiny tracks the dependencies for you. The core of reactivity is defining how outputs depend on inputs, and Shiny figures out the rest.