particle_deterministic: Deterministic particle likelihood
In mrc-ide/mcstate: Monte Carlo Methods for State Space Models
particle_deterministic R Documentation
Deterministic particle likelihood
Description
Create a deterministic version of the
particle_filter object, which runs a single
particle deterministically.
Public fields
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.
Methods
Public methods
-
-
-
-
-
-
-
-
Method new()
Create the particle filter
Usage
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
)
Arguments
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
Method run()
Run the deterministic particle filter
Usage
particle_deterministic$run(
pars = list(),
save_history = FALSE,
save_restart = NULL,
min_log_likelihood = -Inf
)
Arguments
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.
Returns
A single numeric value representing the log-likelihood
(-Inf if the model is impossible)
Method 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().
Usage
particle_deterministic$run_begin(
pars,
save_history = FALSE,
save_restart = NULL,
min_log_likelihood = -Inf
)
Arguments
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.
Returns
An object of class particle_deterministic_state, with methods
step and end. This interface is still subject to change.
Method 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.
Usage
particle_deterministic$state(index_state = NULL)
Arguments
index_stateOptional vector of states to extract
Method 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.
Usage
particle_deterministic$history(index_particle = NULL)
Arguments
index_particleOptional vector of particle indices to return.
If NULL we return all particles' histories.
Method 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.
Usage
particle_deterministic$restart_state(
index_particle = NULL,
save_restart = NULL,
restart_match = FALSE
)
Arguments
index_particleOptional vector of particle indices to return.
If NULL we return all particles' states. Practically because the
only valid value of index_particle is "1", this has no effect and
it is included primarily for compatibility with the stochastic
interface.
Method 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.
Usage
particle_deterministic$inputs()
Method 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.
Usage
particle_deterministic$set_n_threads(n_threads)
Arguments
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).
mrc-ide/mcstate documentation built on July 3, 2024, 1:34 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| particle_deterministic | R Documentation |
Deterministic particle likelihood
Description
Create a deterministic version of the
particle_filter object, which runs a single
particle deterministically.
Public fields
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_parameterswill always beTRUE.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_parametersisFALSEthis 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.
Methods
Public methods
Method new()
Create the particle filter
Usage
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 )
Arguments
dataThe data set to be used for the particle filter, created by
particle_filter_data(). This is essentially adata.frame()with at least columnstime_startandtime_end, along with any additional data used in thecomparefunction, and additional information about how your steps relate to time.modelA stochastic model to use. Must be a
dust_generatorobject.compareA comparison function. Must take arguments
state,observedandparsas arguments (though the arguments may have different names).stateis the simulated model state (a matrix with as many rows as there are state variables and as many columns as there are particles,datais alistof observed data corresponding to the current time's row in thedataobject provided here in the constructor.parsis any additional parameters passed through to the comparison function (via theparsargument 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 elementsrun(indices to return at the end of each run, passed through to your compare function) andstate(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 forindex),n_particles(the number of particles that the particle filter is using) andpars(parameters passed in in the$runmethod via theparsargument). It must return a list, which can have the elementsstate(initial model state, passed to the particle filter - either a vector or a matrix, and overriding the initial conditions provided by your model) andtime(the initial time, overriding the first time step of your data - this must occur within your first epoch in yourdataprovided to the constructor, i.e., not less than the first element oftime_startand not more thantime_end). Your function can also return a vector or matrix ofstateand not alter the starting time, which is equivalent to returninglist(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
Method run()
Run the deterministic particle filter
Usage
particle_deterministic$run( pars = list(), save_history = FALSE, save_restart = NULL, min_log_likelihood = -Inf )
Arguments
parsA list representing parameters. This will be passed as the
parsargument to your model, to yourcomparefunction, and (if using) to yourinitialfunction. It must be an R list (not vector orNULL) 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
$historymethod 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.
Returns
A single numeric value representing the log-likelihood
(-Inf if the model is impossible)
Method 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().
Usage
particle_deterministic$run_begin( pars, save_history = FALSE, save_restart = NULL, min_log_likelihood = -Inf )
Arguments
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.
Returns
An object of class particle_deterministic_state, with methods
step and end. This interface is still subject to change.
Method 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.
Usage
particle_deterministic$state(index_state = NULL)
Arguments
index_stateOptional vector of states to extract
Method 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.
Usage
particle_deterministic$history(index_particle = NULL)
Arguments
index_particleOptional vector of particle indices to return. If
NULLwe return all particles' histories.
Method 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.
Usage
particle_deterministic$restart_state( index_particle = NULL, save_restart = NULL, restart_match = FALSE )
Arguments
index_particleOptional vector of particle indices to return. If
NULLwe return all particles' states. Practically because the only valid value of index_particle is "1", this has no effect and it is included primarily for compatibility with the stochastic interface.
Method 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.
Usage
particle_deterministic$inputs()
Method 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.
Usage
particle_deterministic$set_n_threads(n_threads)
Arguments
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).
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.