Getting Started with puff

#> Loading required package: usethis
#> ℹ Loading puff
library(puff)

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

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().

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:

head(out)
#>               Group.1  Sensor_1
#> 1 2024-01-01 12:00:00 1.5221179
#> 2 2024-01-01 12:01:00 1.6975205
#> 3 2024-01-01 12:02:00 0.5184836
#> 4 2024-01-01 12:03:00 1.5785234
#> 5 2024-01-01 12:04:00 2.0266382
#> 6 2024-01-01 12:05:00 2.0805745

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.:

out |> 
  dplyr::rename(time = Group.1,
                sensor_1_concentration = Sensor_1) |> 
  head()
#>                  time sensor_1_concentration
#> 1 2024-01-01 12:00:00              1.5221179
#> 2 2024-01-01 12:01:00              1.6975205
#> 3 2024-01-01 12:02:00              0.5184836
#> 4 2024-01-01 12:03:00              1.5785234
#> 5 2024-01-01 12:04:00              2.0266382
#> 6 2024-01-01 12:05:00              2.0805745

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

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():

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():

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:

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.