particle_filter_data: Prepare data for use with particle filter

In mrc-ide/mcstate: Monte Carlo Methods for State Space Models

Prepare data for use with particle filter

Description

Prepare data for use with the particle_filter. This function is required to use the particle filter as helps arrange data and be explicit about the off-by-one errors that can occur. It takes as input your data to compare against a model, including some measure of "time". We need to convert this time into model time steps (see Details).

Usage

particle_filter_data(data, time, rate, initial_time = NULL, population = NULL)

Arguments

data	A data.frame() of data
time	The name of a column within data that represents your measure of time. This column must be integer-like. To avoid confusion, this cannot be called step, time, or model_time.
rate	The number of model "time steps" that occur between each time point (in model time time). This must also be integer-like for discrete time models and must be NULL for continuous time models.
initial_time	An initial time to start the model from. This should always be provided, and must be provided for continuous time models. For discrete time models, this is expressed in model time. It must be a non-negative integer and must be at most equal to the first value of the time column, minus 1 (i.e., data[[time]] - 1). For historical reasons if not given we take the first value of the time column minus one, but with a warning - this behaviour will be removed in a future version of mcstate.
population	Optionally, the name of a column within data that represents different populations. Must be a factor.

Details

We require that the time variable increments in unit steps; this may be relaxed in future to even steps, or possibly irregular steps, but for now this assumption is required. We assume that the data in the first column is recorded at the end of a period of 1 time unit. So if you have in the first column ⁠t = 10, data = 100⁠ we assume that the model steps from t = 9 to to t = 10 and at that period the data has value 100.

For continuous time models, time is simple to think about; time is continuous (and real-valued) and really any time is acceptable. For discrete time models there are two correlated measures of time we need to consider - (1) the dust "time step", a non-negative integer value that increases in unit steps, and (2) the "model time" which is related to the dust time step based on the rate parameter here as ⁠<model time> = <dust time> * <rate>⁠. For a concrete example, consider a model where we want to think in terms of days, but which we take 10 steps per day. Time step 0 and model time 0 are the same, but day 1 occurs at step 10, day 15 at step 150 and so on.

Value

If population is NULL, a data.frame with new columns time_start and time_end (required by particle_filter), along side all previous data except for the time variable, which is replaced by new ⁠<time>_start⁠ and ⁠<time>_end⁠ columns. If population is not NULL then a named list of data.frames as described above where each element represents populations in the order specified in the data.

Examples

d <- data.frame(day = 5:20, y = runif(16))
mcstate::particle_filter_data(d, "day", rate = 4, initial_time = 4)

# If providing an initial day, then the first epoch of simulation
# will be longer (see the first row)
mcstate::particle_filter_data(d, "day", rate = 4, initial_time = 0)

# If including populations:
d <- data.frame(day = 5:20, y = runif(16),
                population = factor(rep(letters[1:2], each = 16)))
mcstate::particle_filter_data(d, "day", 4, 0, "population")

mrc-ide/mcstate documentation built on July 3, 2024, 1:34 p.m.