pmcmc_parameters_nested: pmcmc_parameters_nested

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

pmcmc_parameters_nested

Description

Construct nested parameters for use with pmcmc(). This creates a utility object that is used internally to work with parameters that may be fixed and the same for all given populations, or varied and possibly-different between populations. Most users only need to construct this object, but see the examples for how it can be used.

Methods

Public methods

• pmcmc_parameters_nested$new()

• pmcmc_parameters_nested$names()

• pmcmc_parameters_nested$populations()

• pmcmc_parameters_nested$validate()

• pmcmc_parameters_nested$summary()

• pmcmc_parameters_nested$initial()

• pmcmc_parameters_nested$mean()

• pmcmc_parameters_nested$vcv()

• pmcmc_parameters_nested$prior()

• pmcmc_parameters_nested$propose()

• pmcmc_parameters_nested$model()

• pmcmc_parameters_nested$fix()

---

Method new()

Create the pmcmc_parameters object

Usage

pmcmc_parameters_nested$new(
  parameters,
  proposal_varied = NULL,
  proposal_fixed = NULL,
  populations = NULL,
  transform = NULL
)

Arguments

parameters

A list of pmcmc_parameter or pmcmc_varied_parameter objects, each of which describe a single (possibly-varying) parameter in your model. If parameters is named, then these names must match the ⁠$name⁠ element of each parameter that is used (this is verified).

proposal_varied, proposal_fixed

Square proposal matrices corresponding to the variance-covariance matrix of a multivariate gaussian distribution used to generate new varied and fixed parameters respectively.'. They must have the same number of rows and columns as there are varied and fixed parameters respectively. The names must correspond exactly to the names in parameters. Because it corresponds to a variance-covariance matrix it must be symmetric and positive definite.

populations

Specifies the names of the different populations that the varying parameters change according to. Only required if no pmcmc_varied_parameter objects are included in parameters. Otherwise population names are taken from those objects.

transform

An optional transformation function to apply to your parameter vector immediately before passing it to the model function. If not given, then as.list is used, as dust models require this. However, if you need to generate derived parameters from those being actively sampled you can do arbitrary transformations here.

---

Method names()

Return the names of the parameters

Usage

pmcmc_parameters_nested$names(type = "both")

Arguments

type

One of "both" (the default, all parameters), "fixed" (parameters that are shared across populations) or "varied" (parameters that vary over populations).

---

Method populations()

Return the names of the populations

Usage

pmcmc_parameters_nested$populations()

---

Method validate()

Validate a parameter matrix. This method checks that your matrix has the expected size (rows according to parameters, columns to populations) and if named that the names are exactly what is expected. It also verifies that the fixed parameters are same across all populations.

Usage

pmcmc_parameters_nested$validate(theta)

Arguments

theta

a parameter matrix

---

Method summary()

Return a data.frame with information about parameters (name, min, max, integer, type (fixed or varied) and population)

Usage

pmcmc_parameters_nested$summary()

---

Method initial()

Return the initial parameter values as a named matrix with rows corresponding to parameters and columns to populations.

Usage

pmcmc_parameters_nested$initial()

---

Method mean()

Return the estimate of the mean of the parameters, as set when created (this is not updated by any fitting!)

Usage

pmcmc_parameters_nested$mean(type)

---

Method vcv()

Return the variance-covariance matrix used for the proposal.

Usage

pmcmc_parameters_nested$vcv(type)

---

Method prior()

Compute the prior(s) for a parameter matrix. Returns a named vector with names corresponding to populations.

Usage

pmcmc_parameters_nested$prior(theta)

Arguments

theta

a parameter matrix with columns in the same order as ⁠$names()⁠ and rows in the same order as ⁠$populations()⁠.

---

Method propose()

This proposes a new parameter matrix given your current matrix and the variance-covariance matrices of the proposal kernels, rounds any integer values, and reflects bounded parameters until they lie within min:max. Returns matrix with rows corresponding to parameters and columns to populations (i.e., the same orientation as theta).

Usage

pmcmc_parameters_nested$propose(theta, type, scale = 1, vcv = NULL)

Arguments

theta

a parameter matrix with rows in the same order as ⁠$names()⁠ and columns in the same order as ⁠$populations()⁠.

type

specifies which type of parameters should be proposed, either fixed parameters only ("fixed"), varied only ("varied"), or both ("both") types. For 'fixed' and 'varied', parameters of the other type are left unchanged.

scale

an optional scaling factor to apply to the proposal distribution. This may be useful in sampling starting points. The parameter is equivalent to a multiplicative factor applied to the variance covariance matrix.

---

Method model()

Apply the model transformation function to a parameter matrix.

Usage

pmcmc_parameters_nested$model(theta)

Arguments

theta

a parameter matrix with rows in the same order as ⁠$names()⁠ and columns in the same order as ⁠$populations()⁠.

---

Method fix()

Set some parameters to fixed values. Use this to reduce the dimensionality of your system. Note that this function has an unfortunate name collision - we use "fixed" and "varied" parameters generally to refer to ones that are fixed across populations or which vary among populations. However, in the context of this method "fixed" refers to parameters which will be set to a single value and no longer used in inference.

Usage

pmcmc_parameters_nested$fix(fixed)

Arguments

fixed

a named vector of parameters to fix

Examples

# Construct an object with two varied parameters ('a' and 'b'),
# two fixed parameters ('c' and 'd') and two populations ('p1' and 'p2')
parameters <- list(mcstate::pmcmc_varied_parameter("a", c("p1", "p2"), 2),
                   mcstate::pmcmc_varied_parameter("b", c("p1", "p2"), 2),
                   mcstate::pmcmc_parameter("c", 3),
                   mcstate::pmcmc_parameter("d", 4))
proposal_fixed <- diag(2)
proposal_varied <- diag(2) + 1
pars <- mcstate::pmcmc_parameters_nested$new(parameters, proposal_varied,
                                             proposal_fixed)

# Initial parameters
p <- pars$initial()
p

# Propose a new parameter point
pars$propose(p, type = "both")
pars$propose(p, type = "fixed")
pars$propose(p, type = "varied")

# Information about parameters:
pars$names()
pars$names("fixed")
pars$names("varied")
pars$summary()

# Compute log prior probability, per population
pars$prior(p)

# Transform data for your model
pars$model(p)

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