Create a deterministic version of the
particle_filter object, which runs a single
particle deterministically.
modelThe dust model generator being simulated (cannot be re-bound)
has_multiple_parametersLogical, indicating if the
deterministic particle requires multiple parameter sets in a list
as inputs, and if it it will produce a vector of likelihoods
the same length (read only). The parameter sets may or may
not use the same data (see has_multiple_data).
has_multiple_dataLogical, indicating if the deterministic
particle simultaneously calculates the likelihood for multiple
parameter sets (read only). If TRUE, has_multiple_parameters
will always be TRUE.
n_parametersThe number of parameter sets used by this
deterministic particle (read only). The returned vector of
likelihoods will be this length, and if has_multiple_parameters
is FALSE this will be 1.
n_dataThe number of data sets used by this deterministic
particle (read only). This will either be 1 or the same value as
n_parameters.
new()Create the particle filter
particle_deterministic$new(
data,
model,
compare,
index = NULL,
initial = NULL,
constant_log_likelihood = NULL,
n_threads = 1L,
n_parameters = NULL,
stochastic_schedule = NULL,
ode_control = NULL
)dataThe data set to be used for the particle filter,
created by particle_filter_data(). This is essentially
a data.frame() with at least columns time_start
and time_end, along with any additional data used in the
compare function, and additional information about how your
steps relate to time.
modelA stochastic model to use. Must be a
dust_generator object.
compareA comparison function. Must take arguments
state, observed and pars as arguments (though the arguments
may have different names). state is the simulated model state
(a matrix with as many rows as there are state variables and as
many columns as there are particles, data
is a list of observed data corresponding to the current
time's row in the data object provided here in the
constructor. pars is any additional parameters passed
through to the comparison function (via the pars
argument to $run).
indexAn index function. This is used to compute the
"interesting" indexes of your model. It must be a function of
one argument, which will be the result of calling the
$info() method on your model. It should return a list
with elements run (indices to return at the end of each
run, passed through to your compare function) and state
(indices to return if saving state). These indices can overlap
but do not have to. This argument is optional but using it will
likely speed up your simulation if you have more than a few
states as it will reduce the amount of memory copied back and
forth.
initialA function to generate initial conditions. If
given, then this function must accept 3 arguments: info
(the result of calling $info() as for index),
n_particles (the number of particles that the particle
filter is using) and pars (parameters passed in in the
$run method via the pars argument). It
must return a list, which can have the elements state
(initial model state, passed to the particle filter - either a
vector or a matrix, and overriding the initial conditions
provided by your model) and time (the initial time,
overriding the first time step of your data - this must occur within
your first epoch in your data provided to the
constructor, i.e., not less than the first element of
time_start and not more than time_end). Your function
can also return a vector or matrix of state and not alter
the starting time, which is equivalent to returning
list(state = state, time = NULL).
(TODO: this no longer is allowed, and the docs might be out of date?)
constant_log_likelihoodAn optional function, taking the
model parameters, that computes the constant part of the
log-likelihood value (if any). You can use this where your
likelihood depends both on the time series (via data) but also
on some non-temporal data. You should bind any non-parameter
dependencies into this closure. This is applied at the
beginning of the filter run, so represents the initial
condition of the marginal log likelihood value propagated by
the process.
n_threadsNumber of threads to use when running the simulation. Defaults to 1, and should not be set higher than the number of cores available to the machine. This currently has no effect as the simulation will be run in serial on a single particle for now.
n_parametersNumber of parameter sets required. This, along
with data, controls the interpretation of how the deterministic
particle, and importantly will add an additional dimension to
most outputs (scalars become vectors, vectors become matrices etc).
stochastic_scheduleVector of times to perform stochastic updates, for continuous time models. Note that despite the name, these will be applied deterministically (i.e., replacing the stochastic draw with its expectation).
ode_controlTuning control for the ODE stepper, for continuous time (ODE) models
run()Run the deterministic particle filter
particle_deterministic$run(
pars = list(),
save_history = FALSE,
save_restart = NULL,
min_log_likelihood = -Inf
)parsA list representing parameters. This will be passed as
the pars argument to your model, to your compare
function, and (if using) to your initial function. It must
be an R list (not vector or NULL) because that is what a
dust model currently requires on initialisation or $reset - we
may relax this later. You may want to put your observation and
initial parameters under their own keys (e.g.,
pars$initial$whatever), but this is up to you. Extra keys
are silently ignored by dust models.
save_historyLogical, indicating if the history of all
particles should be saved. If saving history, then it can be
queried later with the $history method on the object.
save_restartAn integer vector of time points to save restart infomation for. Not currently supported.
min_log_likelihoodNot currently supported, exists to match the inteface with particle_filter. Providing a value larger than -Inf will cause an error.
run_begin()Begin a deterministic run. This is part of the
"advanced" interface; typically you will want to use $run()
which provides a user-facing wrapper around
this function. Once created with $run_begin(), you should take
as many steps as needed with $step().
particle_deterministic$run_begin(
pars,
save_history = FALSE,
save_restart = NULL,
min_log_likelihood = -Inf
)parsA list representing parameters. See $run_many()
for details (and not $run())
save_historyLogical, indicating if the history of all
particles should be saved. See $run() for details.
save_restartTimes to save restart state at. See $run() for
details.
min_log_likelihoodNot currently supported, exists to match the inteface with particle_filter. Providing a value larger than -Inf will cause an error.
state()Extract the current model state, optionally filtering. If the model has not yet been run, then this method will throw an error. Returns a matrix with the number of rows being the number of model states, and the number of columns being the number of particles.
history()Extract the particle trajectories. Requires that
the model was run with save_history = TRUE, which does
incur a performance cost. This method will throw an error if
the model has not run, or was run without save_history = TRUE. Returns a 3d array with dimensions corresponding to (1)
model state, filtered by index$run if provided, (2)
particle (following index_particle if provided), (3)
time point.
restart_state()Return the full particle filter state at points back in time
that were saved with the save_restart argument to
$run(). If available, this will return a 3d array, with
dimensions representing (1) particle state, (2) particle index,
(3) time point. If multiple parameters are used then returns a 4d array,
with dimensions representing (1) particle state, (2) particle index,
(3) parameter, (4) time point. This could be quite large, especially
if you are using the index argument to create the particle filter
and return a subset of all state generally. In the stochastic version,
this is different the saved trajectories returned by $history()
because earlier saved state is not filtered by later filtering,
but in the deterministic model we run with a single particle so it
is the same.
inputs()Return a list of inputs used to configure the deterministic particle filter. These correspond directly to the argument names for the constructor and are the same as the input arguments.
set_n_threads()Set the number of threads used by the particle filter (and dust model) after creation. This can be used to allocate additional (or subtract excess) computing power from the deterministic filter Returns (invisibly) the previous value.
n_threadsThe new number of threads to use. You may want to
wrap this argument in dust::dust_openmp_threads() in order to
verify that you can actually use the number of threads
requested (based on environment variables and OpenMP support).