```{r, setup, include=FALSE}
library(mosaic)   # Load additional packages here 
library(tidyverse)
library(ggmap)
library(OpenStreetMap)
knitr::opts_chunk$set(
  tidy=FALSE,     # display code as typed
  size="small")   # slightly smaller font for code
options(digits = 4)
```

# Overview

To explore how the selection of data analysis tools can fundamentally shape what is highlighted in an investigation, we conducted a comparative analysis using several popular tools from multiple tool genres: R (scripting), CODAP (visual/pedagogical), Google Sheets (spreadsheet), and Tableau (visual/commercial).

This file demonstrates how R can be used to carry out these analyses.

The associated commissioned paper, supplementary materials, RMarkdown file, and dataset can be found at https://nicholasjhorton.github.io/K12-Data-Tools.

# Motivating data 

Using each tool, we loaded the same CSV (comma separated value) dataset focused on the recent historical migration patterns of the American Lobster (*Homarus americanus*) off the coast of Northern East Coast of the United States and Southern East Coast of Canada.
These data are part of a much larger repository of data about aquatic species maintained by the OceanAdapt project (<https://oceanadapt.rutgers.edu>).
They track position including the mean latitude, longitude, and depth of lobsters for different regions/seasons between the years of 1970 and 2020.
The dataset is structured such that each row includes one observation record including \texttt{year}, \texttt{region}, \texttt{latitude}, \texttt{longitude}, and \texttt{depth}.

It is well established that American lobster populations have been moving north in recent years; examining this northward movement was the focus of our investigation.
We selected this examination for the vignettes because it reflects a popular 'alternative' data type (geospatial data); it is deeply embedded in a specific context that connects to other disciplines (ecosystems); and there is a clear and consequential pattern to observe that emerges from relatively messy, multivariate data.

See https://www.nationalacademies.org/our-work/foundations-of-data-science-for-students-in-grades-k-12-a-workshop for more information about the NASEM Foundations of Data Science for Students in Grades K-12 workshop.

### Executive summary of the motivating dataset

- the points indicate the centroid of the catch of lobsters for a particular year
- there is a separate point for each of the main regions/seasons
- there is a shift to the north
- this might indicate impacts of climate change

### Other notes about the analyses

- multivariate displays are helpful in communicating this result
- mapping is also important for this example, providing context in terms of geographic location
- certain data tools allow easy entry to the problem while others allow advanced visualizaton and analysis
- data science features many things, among them a variety of data types (e.g., maps, text, networks)



# R

R is an open-source scripting environment for statistical computing and graphics that has been widely adopted (https://www.r-project.org).
RStudio is an integrated development environment (IDE) that was designed to facilitate use of R for experts and new users (https://www.rstudio.com/products/rstudio).
The `mosaic` and `ggformula` packages were designed to provide a simplified interface to modeling and visualization in R (https://doi.org/10.32614/RJ-2017-024).

We use these packages to explore the lobster data.
The analyses are scaffolded using an R Markdown file (https://rmarkdown.rstudio.com, see also https://escholarship.org/uc/item/90b2f5xh) which is a text-based format to undertake reproducible analyses.


### Ingest data

We begin by reading in the data.
The base pipe operator (`|>`) allows the output of one function to be provided as the input to the next.
This piping helps clarify the flow of operations (read the CSV, clean up the names, including only the lobsters, and clump the Northeast US catch into a single group).


```{r message = FALSE}
lobsters <- readr::read_csv("fishdata.csv") |>
  janitor::clean_names() |>
  filter(common_name == "American lobster") |>
  mutate(region_3 = if_else(
    region %in% c("Northeast US Fall", "Northeast US Spring"),
    "Northeast US",
    region)
  )
glimpse(lobsters)
```

We see that there are 187 observations (each one a geographical location for each region for a given year).

### Exploration 


### Summary statistics and distributions

A number of univariate summaries can be calculated.

```{r}
tally(~ region_3, margins = TRUE, data = lobsters)
tally(~ region_3, format = "percent", data = lobsters)
tally(~ year, margins = TRUE, data = lobsters)
favstats(~ latitude, data = lobsters) # needed for bottom and top
favstats(~ longitude, data = lobsters) # needed for left and right
```


A straightforward way to identify what map region to display is by calculating summary statistics for latitude and longitude.


### Simple map

```{r message = FALSE, warning = FALSE}
myLocation <- c(
  left = -71.0, 
  bottom = 40.78, 
  right = -60.70, 
  top = 47.23
)
myMap <- get_map(
  location = myLocation, 
  source = "stamen",
  maptype = "watercolor",
  crop=FALSE
)
ggmap(myMap) + 
  geom_point(
    aes(x = longitude, y = latitude, color = region_3, size = 0.2), 
    data = lobsters
  )
```

Routines in the `ggmap` package (https://journal.r-project.org/archive/2013-1/kahle-wickham.pdf) are used to generate the maps.

### More sophisticated map

A more sophisticated map colors the points (depending on year) and cleans up the axis labels.
We see the trend of northward movement when comparing the years.

```{r warning = FALSE}
ggmap(myMap) + 
  geom_point(
    aes(x = longitude, y = latitude, color = year), 
    data = lobsters
  ) +
  labs(x = "longitude", y = "latitude")
```

### Scatterplot of latitude

A scatterplot is an alternative representation of these data.
Here we generate a scatterplot where the points are colored by the three level region variable.

```{r warning = FALSE}
gf_point(
  latitude ~ year,
  color = ~ region_3, 
  shape = ~ region_3,
  data = lobsters
) |>
  gf_lm()
```

Both of these displays are static, however dynamic graphical displays are available within R (see for example https://mdsr-book.github.io/mdsr2e/ch-vizIII.html).

It is possible to further create a map that distinguishes regions by hue and years by saturation using similar commands; though we chose to end the vignette here.

