Compute Sigma Values Based on Stability Class and Distance

Description

Compute Sigma Values Based on Stability Class and Distance

Usage

compute_sigma_vals(stab_class, total_dist)

Arguments

Value

2-row matrix with sigma_y (row 1) and sigma_z (row 2) values

Examples

out <- compute_sigma_vals("A", 0.7)

Create a Site Map of Sensors and Sources

Description

This function generates a site map with an adjacent compass rose.

Usage

create_site_map(sensors, sources, text_size = 12)

Arguments

Value

A patchwork-combined ggplot object: site map + compass rose.

Examples

source_coords <- c(0, 0, 2.5)

n_sensors <- 8
radius <- 20
z_height <- 2.0

angles <- seq(0, 2 * pi, length.out = n_sensors + 1)[- (n_sensors + 1)]

sensor_coords <- matrix(
  cbind(radius * cos(angles), radius * sin(angles), rep(z_height, n_sensors)),
  ncol = 3
)

create_site_map(sensor_coords, source_coords)

Faceted Time Series Plot of Methane Concentrations and Wind Data

Description

This function creates a faceted bubble plot of methane concentrations and a shared wind rose plot.

Usage

faceted_time_series_plot(
  sensor_concentrations,
  sensor_coords,
  wind_data,
  start_time,
  end_time,
  output_dt,
  text_size = 12
)

Arguments

Value

A ggplot object: faceted concentration plot + single wind rose plot.

Examples

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"
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)
)
source_coords <- c(0, 0, 2.5)
sensor_coords <- matrix(c(-6.525403221327715e-15, -35.52264, 2.01775), ncol = 3, byrow = TRUE)

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
)

faceted_time_series_plot(out, sensor_coords,
  wind_data, as.POSIXct(start_time), as.POSIXct(end_time),
  output_dt
  )

Alternate version with wind rose at each time step + scatter plot of methane concentration time series

Description

Alternate version with wind rose at each time step + scatter plot of methane concentration time series

Usage

faceted_time_series_plot2(
  sensor_concentrations,
  sensor_coords,
  wind_data,
  start_time,
  end_time,
  output_dt,
  text_size = 12
)

Arguments

Value

A ggplot object with faceted time series plots of methane concentrations and wind rose data.

Examples

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"
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)
)
source_coords <- c(0, 0, 2.5)
sensor_coords <- matrix(c(-6.525403221327715e-15, -35.52264, 2.01775), ncol = 3, byrow = TRUE)

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
)

faceted_time_series_plot2(out, sensor_coords,
  wind_data, as.POSIXct(start_time), as.POSIXct(end_time),
  output_dt
  )

Determine Stability Class Based on Wind Speed and Time of Day

Description

This function calculates the stability class based on wind speed (U) and the time of day. It categorizes the atmosphere's stability as one of several classes (A-F) depending on the inputs.

Usage

get_stab_class(U, time)

Arguments

Value

A character vector representing the stability class(es) ("A" to "F").

Examples

out <- get_stab_class(3, 12)

Gaussian Puff Concentration Calculation

Description

Calculates the concentration of an emission event at a specified location and time due to a Gaussian puff.

This function uses wind speed and direction components, advection adjustments, and stability class calculations to accurately measure the dispersion of a puff in the atmosphere.

Usage

gpuff(Q, stab_class, x_p, y_p, x_r_vec, y_r_vec, z_r_vec, total_dist, H, U)

Arguments

Value

Numeric. Pollutant concentration at the specified (x, y, z) locations and time 't'.

Examples

out <- gpuff(Q = 1, stab_class = "D", x_p = 0, y_p = 0,
  x_r_vec = 100, y_r_vec = 0, z_r_vec = 2,
  total_dist = 100, H = 2, U = 5
)

Resample wind_speeds and wind_directions to the simulation resolution by interpolation

Description

Resample wind_speeds and wind_directions to the simulation resolution by interpolation

Usage

interpolate_wind_data(wind_speeds, wind_directions, sim_start, sim_end, puff_dt)

Arguments

Value

Quantities corresponding to the conversion direction

Examples

out <- interpolate_wind_data(c(2, 3), c(90, 180),
  "2024-01-01 00:00:00", "2024-01-01 01:00:00", 300
)

Determine Whether a Time is During the Day

Description

This function checks the time and classifies it as day or not

Usage

is_day(time)

Arguments

Value

A character T or F representing whether or not it is daytime.

Examples

out <- is_day(8)

Plot a 2D Animated Heatmap for Concentration Over Time

Description

This function generates a 2D animated heatmap using 'plotly' to visualize the movement of a plume over time. The animation is based on grid concentration data from 'simulate_grid_mode()' output.

Usage

plot_2d_animated(
  data,
  grid_coords,
  start,
  end,
  output_dt,
  frames = 100,
  transition = 99,
  save = FALSE,
  interpolate_grid = FALSE,
  granularity = 100
)

Arguments

Value

A 'plotly' object representing the animated heatmap.

Examples

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

grid_coords <- list(
  x = seq(-2, 2, by = 1),
  y = seq(-2, 2, by = 1),
  z = seq(0, 5, by = 1)
)

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(data = out,
  grid_coords = grid_coords,
  start = start_time,
  end = end_time,
  output_dt = output_dt)

Plot a 3D Animated Plot for Concentration Over Time

Description

This function generates a 3D animated plot (scatter or contour) using 'plotly' to visualize the movement of a plume over time. The animation is based on grid concentration data from 'simulate_grid_mode()' output.

Usage

plot_3d_animated(
  data,
  grid_coords,
  start,
  end,
  output_dt,
  frames = 100,
  transition = 99,
  plot_type = "contour",
  save = FALSE
)

Arguments

Value

A 'plotly' object representing the animated plot.

Examples

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

grid_coords <- list(
  x = seq(-2, 2, by = 1),
  y = seq(-2, 2, by = 1),
  z = seq(0, 5, by = 1)
)

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_3d_animated(out,
   grid_coords,
   start_time, end_time,
   output_dt)

Simulate Atmospheric Concentration on a Grid

Description

Simulates methane concentrations at each grid point over time using the Gaussian puff forward model. Supports one or more emission sources. Each puff retains constant wind speed and direction throughout its lifetime, and corresponding dispersion parameters are determined at the time of emission.

Usage

simulate_grid_mode(start_time, end_time, source_coords, emission_rate, wind_data,
  grid_coords, sim_dt, puff_dt, output_dt, puff_duration, ws, wd)

Arguments

Details

- Each source (from one to many) emits puffs at intervals of puff_dt. - Each puff maintains a fixed wind vector and dispersion parameters. - Puffs are advected over time based on their individual wind vectors. - Concentration contributions from all active puffs are computed at each grid point and summed. - Concentrations are aggregated and returned at a coarser time resolution defined by output_dt.

Value

A matrix of concentrations (ppm) with rows representing output time steps and columns representing grid points. Columns correspond to the flattened grid defined by expand.grid(grid_coords).

Note

All time parameters should be positive, with 'puff_dt > sim_dt' and 'out_dt > sim_dt'. Also, 'puff_dt' should be a positive integer multiple of 'sim_dt', i.e. 'puff_dt = n*sim_dt' for some positive integer 'n'. This prevents the code having to interpolate the concentration values in time, although it is likely that this constraint could be avoided.

References

Jia, M., Fish, R., Daniels, W., Sprinkle, B. and Hammerling, D. (2024) <doi:10.26434/chemrxiv-2023-hc95q-v3>

Examples

set.seed(123)

sim_dt <- 7
puff_dt <- 7
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 <- 3.5
wind_data <- data.frame(
  wind_u = runif(3601, min = -3, max = 0.7),
  wind_v = runif(3601, min = -3, 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
  )

Simulate Atmospheric Concentration at Sensor Locations

Description

This function simulates atmospheric methane concentrations at one or more sensor locations using a Gaussian puff forward model. It supports one or multiple emission sources and assumes each puff maintains a constant wind speed and direction throughout its lifetime. The function accounts for puff dispersion based on wind conditions and atmospheric stability class.

Usage

simulate_sensor_mode(start_time, end_time, source_coords, emission_rate, wind_data,
  sensor_coords, sim_dt, puff_dt, output_dt, puff_duration, ws, wd)

Arguments

Details

- Each source emits puffs at regular intervals ('puff_dt') with a fixed mass based on 'emission_rate'. - Wind speed and direction at the time of puff emission are used to advect the puff and determine dispersion. - Puff position is analytically computed at each timestep based on wind, without tracking in-between steps. - Puff dispersion is computed using stability-class-based sigma values from a fast lookup. - Total sensor concentration is the sum of all active puff contributions at each timestep. - Concentrations are aggregated into intervals matching 'output_dt' before being returned.

Value

A data frame with aggregated sensor concentrations across time. Rows represent time intervals ('output_dt'), columns represent sensors ('Sensor_1', 'Sensor_2', etc.).

Note

All time parameters should be positive, with 'puff_dt > sim_dt' and 'out_dt > sim_dt'. Also, 'puff_dt' should be a positive integer multiple of 'sim_dt', i.e. 'puff_dt = n*sim_dt' for some positive integer 'n'. This prevents the code having to interpolate the concentration values in time, although it is likely that this constraint could be avoided.

References

Jia, M., Fish, R., Daniels, W., Sprinkle, B. and Hammerling, D. (2024) <doi:10.26434/chemrxiv-2023-hc95q-v3>

Examples

set.seed(123)
sim_dt <- 10
puff_dt <- 10
output_dt <- 60
start_time <- as.POSIXct("2024-01-01 12:00:00")
end_time <- as.POSIXct("2024-01-01 13:00:00")

source_coords <- matrix(c(0, 0, 2.5), ncol = 3, byrow = TRUE)

sensor_coords <- matrix(c(
   -20, 0, 2.0,
     0, -20, 2.0,
    20, 0, 2.0,
     0, 20, 2.0,
    10, 10, 2.0
), ncol = 3, byrow = TRUE)

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

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

Plot Multiple Emission Rate Sensor Concentrations

Description

This function generates a faceted (if multiple sensors) bubble plot of sensor concentrations over time using precomputed sensor data (e.g., from 'simulate_sensor_mode()').

Usage

single_emission_rate_plot(sensor_concentrations, sensor_coords, text_size = 12)

Arguments

Value

A ggplot object showing sensor concentrations over time, faceted by sensor.

Examples

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"
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)
)
source_coords <- c(0, 0, 2.5)
sensor_coords <- matrix(c(-6.525403221327715e-15, -35.52264, 2.01775), ncol = 3, byrow = TRUE)

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
)

single_emission_rate_plot(out, sensor_coords)

Plot Time Series of Sensor Concentrations

Description

This function plots the time series of sensor concentrations.

Usage

time_series_plot(sensor_concentrations, text_size = 12)

Arguments

Value

A ggplot object showing the time series of sensor concentrations.

Examples

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"
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)
)
source_coords <- c(0, 0, 2.5)
sensor_coords <- matrix(c(-6.525403221327715e-15, -35.52264, 2.01775), ncol = 3, byrow = TRUE)

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
)

time_series_plot(out)

Convert between (ws, wd) and (u,v)

Description

This function converts between coordinate systems by changing from degrees to radians

Usage

wind_vector_convert(wind_speeds,wind_directions)

Arguments

Value

Quantities corresponding to the conversion direction

Examples

out <- wind_vector_convert(c(5, 10), c(0, 90))