Help for package dlmwwbe

Title:

Dynamic Linear Model for Wastewater-Based Epidemiology

Version:

0.1.0

Description:

Implement dynamic linear models outlined in Shumway and Stoffer (2025) <doi:10.1007/978-3-031-70584-7>. Two model structures for data smoothing and forecasting are considered. The specific models proposed will be added once the manuscript is published.

License:

GPL (≥ 3)

Encoding:

UTF-8

LazyData:

true

RoxygenNote:

7.3.2

Imports:

dlm

Suggests:

knitr, rmarkdown

VignetteBuilder:

knitr

NeedsCompilation:

Packaged:

2025-05-21 20:43:34 UTC; difanouyang

Author:

Difan Ouyang [aut, cre], Lappui Chung [aut], Charles Doss [aut]

Maintainer:

Difan Ouyang <ouyan146@umn.edu>

Depends:

R (≥ 3.5.0)

Repository:

CRAN

Date/Publication:

2025-05-26 13:10:05 UTC

Fit a Dynamic Local Level Model (DLM)

Description

Fits a dynamic linear model (DLM) using maximum likelihood estimation.

Usage

dllm(
  data,
  obs_cols,
  S = c("univariate", "kvariate"),
  log10 = FALSE,
  date = NULL,
  prior = list(),
  equal.state.var = FALSE,
  equal.obs.var = FALSE,
  init_params = NULL,
  auto_init = TRUE,
  control = list(maxit = 500)
)

Arguments

data

A data frame containing observed time series data.

obs_cols

Character vector of column names in data to be used as observations.

S

Character; the structure of latent states.

log10

logical; if TRUE, a log10 transformation is applied to the whole data.

date

Optional; the name of the column in data representing date or time.

prior

A list of prior specifications. Default priors are used if not supplied.

equal.state.var

logical; if TRUE the variance is the same across all wastewater state.

equal.obs.var

logical; if TRUE the variance is the same across all wastewater observation.

init_params

Optional numeric vector of initial parameters.

auto_init

Logical; if TRUE (default) and init_params is NULL, initial parameters are estimated automatically.

control

List of control parameters for the optimization routine (dlmMLE).

Details

The function prepares the data, validates inputs, and (if necessary) automatically initializes parameters. It then defines a helper function to build the model via build_dlm and fits the model using maximum likelihood estimation (dlmMLE). Filtering and smoothing are applied to obtain state estimates.

Value

An object of class dllm containing the fitted model, filtered and smoothed estimates, along with fit statistics (log-likelihood, AIC, BIC) and other diagnostic information.

data: The input data.
date: The input vector of date.
obs_cols: Character vector of column names in data to be used as observations.
S: Character; the structure of latent states.
parameters: A list of estimated parameters by maximum likelihood estimation.
logLik: The loglikelihood of the fitted model.
aic: AIC of the fitted model.
bic: BIC of the fitted model.
convergence: An integer code returned by optim
model: An dlm object of the fitted dynamic linear model.
filter: The corresponding dynamic linear filter returned by dlmFilter
smoother: The corresponding dynamic linear smoother returned by dlmSmooth
yf: A matrix of the filtered observed response variables.
ys: A matrix of the smoothed observed response variables.

Examples

data<- wastewater[wastewater$Code == "TC",]
data$SampleDate <- as.Date(data$SampleDate)
fit <- dllm(
equal.state.var=TRUE,
equal.obs.var=FALSE,
log10=TRUE,
data = data,
date = "SampleDate",
obs_cols = c("ORFlab", "Nlab"),
S = 'kvariate')
summary(fit)
plot(fit, type='smoother', plot_data = TRUE)

Build a Predictive Dynamic Linear Model (pdlm) for wastewater-based epidemiology

Description

Constructs a dynamic linear model (DLM) object using the dlm package.

Usage

pdlm(
  data,
  formula,
  lags = 0,
  log10 = TRUE,
  date = NULL,
  prior = list(),
  equal.state.var = TRUE,
  equal.obs.var = TRUE,
  init_params = list(),
  auto_init = TRUE,
  control = list(maxit = 500)
)

Arguments

data

A data frame containing the variables in the model.

formula

An object of class "formula" describing the model to be fitted.

lags

A nonnegative integer indicating the lag of the latent state in the model.

log10

Logical; if TRUE, a log10 transformation is applied to the entire dataset.

date

An optional vector of date indices of the data.

prior

An optional list specifying the prior mean vector and covariance structure of the latent state. If not provided, a naive prior is used.

equal.state.var

Logical; if TRUE, the same variance is assumed across all state components.

equal.obs.var

Logical; if TRUE, the same variance is assumed across all observation components.

init_params

An optional list of initial parameters for the model. Should include Ft, Wt, and Vt: transition coefficients, state variance, and observation variance components respectively.

auto_init

Logical; if TRUE, naive initial parameters are used.

control

An optional list of control parameters for optim().

Value

A dlm object with additional attributes:

formula: The fitted formula.
lags: Number of lags.
data: The input data.
date: The input vector of dates.
parameters: A list of estimated parameters.
logLik: Log-likelihood of the fitted model.
aic: Akaike Information Criterion.
bic: Bayesian Information Criterion.
convergence: The convergence code from optim.
model: The final dlm object.
filter: Output from dlmFilter.
ypred: One-step-ahead predictions.
var.pred: Variance of the predictions.

Examples


data <- wastewaterhealthworker[wastewaterhealthworker$Code == "TC",]
data$SampleDate <- as.Date(data$SampleDate)
fit <- pdlm(
  formula=HealthWorkerCaseCount~WW.tuesday+WW.thursday,
  data = data,
  lags = 2,
  equal.state.var=FALSE,
  equal.obs.var=FALSE,
  log10=TRUE,
  date = "SampleDate")
summary(fit)
plot(fit, conf.int = TRUE)

Plot a Fitted Dynamic Local Level Model

Description

Produces a plot for an object of class dllm (typically created by dllm). The function displays the observed data along with the fitted curves computed using filtered and/or smoothed state estimates.

Usage

## S3 method for class 'dllm'
plot(
  x,
  type = c("smoother", "filter"),
  plot_data = TRUE,
  obs_cols = NULL,
  obs_colors = NULL,
  filter_colors = NULL,
  smoother_colors = NULL,
  conf.int = FALSE,
  sig.level = 0.95,
  ...
)

Arguments

x

An object of class dllm, as returned by dlm.

type

Character; one of "smoother" or "filter" (default: "smoother"). Specifies which fitted curves to display.

plot_data

Logical; if TRUE (default) the observed data points are plotted.

obs_cols

Character; an optional argument specifying the variables to be plotted. If NULL, plot all variables.

obs_colors

Optional character vector specifying custom colors for observed data. If not supplied, a default palette is used.

filter_colors

Optional character vector specifying custom colors for filtered curves. If not supplied, a default palette is used.

smoother_colors

Optional character vector specifying custom colors for smoothed curves. If not supplied, a default palette is used.

conf.int

Logical; if TRUE, plot confidence intervals with the given sig.level.

sig.level

Numeric; significance level for confidence intervals (default: 0.95).

...

Additional graphical parameters to pass to the underlying plotting functions.

Value

This function produces a plot of the fitted DLM and returns NULL invisibly.

Plot a Fitted Predictive Dynamic Linear Model

Description

Produces a plot for an object of class pdlm (typically created by pdlm). The function displays the observed data along with the fitted curves computed using filtered and/or smoothed state estimates.

Usage

## S3 method for class 'pdlm'
plot(x, plot_data = TRUE, conf.int = FALSE, sig.level = 0.95, ...)

Arguments

x

An object of class pdlm, as returned by dlm.

plot_data

Logical; if TRUE (default) the observed data points are plotted.

conf.int

Logical; if TRUE, plot confidence intervals with the given sig.level.

sig.level

Numeric; significance level for confidence intervals (default: 0.95).

...

Additional graphical parameters to pass to the underlying plotting functions.

Value

This function produces a plot of the fitted DLM and returns NULL invisibly.

Summarize a fitted Dynamic Local Level Model object

Description

Provides a brief summary of the fitted dynamic local level model, including parameter estimates and log-likelihood.

Usage

## S3 method for class 'dllm'
summary(object, ...)

Arguments

object

An object of class dllm, as returned by dllm.

...

Additional arguments (not used).

Value

The object is returned invisibly.

Summarize a fitted Predictive Dynamic Linear object

Description

Provides a brief summary of the fitted predictive dynamic linear model, including parameter estimates and log-likelihood.

Usage

## S3 method for class 'pdlm'
summary(object, ...)

Arguments

object

An object of class pdlm, as returned by pdlm.

...

Additional arguments (not used).

Value

The object is returned invisibly.

Dataset wastewater:

Description

A dataset containing the long format of daily wastewater data collected in Minnesota from March 2022 to February 2023. The wastewater was collected twice a week with possible missing values.

Usage

wastewater

Format

A data frame with 1348 rows and 4 variables:

Code: Character. The code name of the treatment plant where the wastewater was sampled.
SampleDate: Date. The sample collection date.
ORFlab: The ORF target.
Nlab: The N target.

Dataset wastewaterhealthworker:

Description

A dataset containing the wide format of weekly wastewater and clinical case data collected in Minnesota from March 2022 to Feburary 2023. The wastewater was collected twice a week with possible missing values.

Usage

wastewaterhealthworker

Format

A data frame with 196 rows and 5 variables:

Code: Character. The code name of the treatment plant where the wastewater was sampled.
SampleDate: Date. The sample collection date.
HealthWorkerCaseCount: Integer. Reported weekly Covid-19 positive case counts.
WW.tuesday: Flow adjusted wastewater measurement from Tuesday samples.
WW.thursday: Flow adjusted wastewater measurement from Thursday samples.