Package 'dlmwwbe'

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.

---