---
title: "Getting Started with `puff`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{getting-started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r echo = FALSE}
library(devtools)
load_all()
```

```{r eval = FALSE}
library(puff)
```

Let's walk through a basic use case for the `puff` package. To do so, we will cover: 

  - Sensor mode
  - Grid mode
  
For each of these "modes", the workflow typically includes something like running the simulation to produce emission concentration values (either at individual *sensor* locations or over the full *grid* of the site), and then plot the results in a variety of ways with a variety of views. The latter task is at the heart of this package, which is the ability to produce accurate, clean, and publication-ready plots. Therefore, this vignette focuses mostly on the plotting capabilities of `puff` rather than the simulation / modeling part. 

## Sensor Mode

Let's start simply with an example in sensor mode via `simulate_sensor_mode()`. 

```{r}
set.seed(123)

sim_dt <- 10
puff_dt <- 10
output_dt <- 60

start_time <- "2024-01-01 12:00:00"
end_time <- "2024-01-01 13:00:00"

source_coords <- c(0, 0, 2.5)
sensor_coords <- matrix(c(-6.525403221327715e-15, -35.52264, 2.01775), ncol = 3, byrow = TRUE)

emission_rate <- 3.5

wind_data <- data.frame(
  wind_u = runif(3601, min = -3, max = 0.7),
  wind_v = runif(3601, min = -3, max = 1.5)
)

out <- out <- simulate_sensor_mode(
  start_time, end_time, 
  source_coords, emission_rate,
  wind_data, 
  sensor_coords,
  sim_dt, puff_dt, output_dt, 
  puff_duration = 1200
)
```

Inspect the output: 

```{r}
head(out)
```

From the output, we can see the `Group.1` corresponds with the timestamps associated with each concentration value at `Sensor_1`. These names are intentionally generic to allow maximal flexibility for the user to rename and define how they want. For example, you might consider renaming for simplicity, e.g.: 

```{r}
out |> 
  dplyr::rename(time = Group.1,
                sensor_1_concentration = Sensor_1) |> 
  head()
```

Now, there are a variety of plotting options for the sensor mode. We will start with a simple time series via `time_series_plot()`:

```{r, fig.align='center', out.width='100%', fig.width=12, fig.height=8}
time_series_plot(out)
```

Or suppose you wanted to include the wind and vary point size by concentration amount. Do so with `faceted_time_series_plot()`:

```{r, fig.align='center', out.width='100%', fig.width=12, fig.height=15}
faceted_time_series_plot(out, 
                         sensor_coords,
                         wind_data, 
                         as.POSIXct(start_time), 
                         as.POSIXct(end_time), 
                         output_dt)
```

You can also easily generate a quick map of the site denoting likely emission sources and sensors via `create_site_map()`:

```{r, fig.align='center', out.width='100%', fig.width=12, fig.height=8}
create_site_map(sensor_coords,
                source_coords)
```

*Note*: all plots are of `ggplot` class. As such, users can further customize and adjust plots in any way that they might any other `ggplot` object (e.g., changing labels, colors, sizes, and so on).

## Grid Mode

Finally, here's a look at running and visualizing in grid mode: 

```{r echo = TRUE, eval = FALSE}
set.seed(123)

sim_dt <- 2
puff_dt <- 2
output_dt <- 60
start_time <- "2024-01-01 12:00:00"
end_time <- "2024-01-01 13:00:00"
source_coords <- c(0, 0, 2.5)
emission_rate <- 5
wind_data <- data.frame(
    wind_u = runif(3601, min = -2, max = 0.7),
    wind_v = runif(3601, min = -2, max = 1.5)
)

grid_coords <- list(
  x = seq(-2, 2, by = 1),
  y = seq(-2, 2, by = 1),
  z = c(2.5)
)


out <- simulate_grid_mode(
  start_time = start_time,
  end_time = end_time,
  source_coords = source_coords,
  emission_rate = emission_rate,
  wind_data = wind_data,
  grid_coords = grid_coords,
  sim_dt = sim_dt,
  puff_dt = puff_dt,
  output_dt = output_dt,
  puff_duration = 1200
  )

plot_2d_animated(
  out, grid_coords, 
  start_time, end_time, output_dt,
  frames = 200,
  transition = 199,
  interpolate_grid = TRUE
  )
```

## Concluding Remarks

This vignette has focused on introducing users to a very basic version of the `puff` package. The package does much more, including simulation and plotting in "grid mode". We encourage wide and creative use to make the most of this powerful package for analyzing and reporting research about methane emissions.