
Simulate Posterior Predictive Responses
Source:R/bayes_scale_simulate.R
simulate.multiScaleR_bayes.RdGenerate replicate responses for fitted or new observations. Each replicate includes joint parameter uncertainty, any requested new-group effects, and the scatter of individual observations around their means, so replicates show the values you might record.
Usage
# S3 method for class 'multiScaleR_bayes'
simulate(
object,
nsim = 1L,
seed = NULL,
newdata = NULL,
kernel_inputs = NULL,
row_id = NULL,
re.form = NULL,
scale_re.form = NULL,
new_scale_levels = c("error", "sample", "zero"),
new_response_levels = c("error", "sample", "zero"),
trials = NULL,
include_fixed = FALSE,
...
)Arguments
- object
A fitted
multiScale_bayes()object with posterior draws, from sampling or either approximation.- nsim
Positive integer number of replicate data sets; default 1.
- seed
Optional positive integer simulation seed. Your own random-number state is restored after simulation, even when it fails.
- newdata
NULL(default) uses the fitted observations. Otherwise a nonempty data frame of new observations that holds the fixed covariates, the offset variables, and the grouping variables of every component you include. Response values are neither needed nor used.- kernel_inputs
Prepared landscape inputs for
newdata, fromkernel_prep()orkernel_prep_by_group(). Required with new data andNULLotherwise. Use the fitted kernel, predictor definitions, and physical map units. See "Match new rows to their landscapes" inpredict.multiScaleR_bayes().- row_id
Name of the column in
newdatathat matches each row to an entry ofkernel_inputs$binned$point_ids, or to a row name ofkernel_inputs$kernel_datfor surface-only inputs. IDs may repeat. The defaultNULLuses the fitted row-ID column when the fit kept it, and the row names ofnewdataotherwise. Supply it for fits saved by older versions of the package. Used only with new data.- re.form
NULL(default) includes the response random effects.NAsets them all to zero while keeping group-specific scales. This is a reference prediction, not an average over the random effects.- scale_re.form
NULL(default) includes the fitted scale random effects and any sampled new ones.NAsets every scale deviation to zero. It is separate fromre.form, which controls response effects.- new_scale_levels, new_response_levels
What to do with a group level that was not in the fitted data, set separately for scale and response random effects.
"error"(default) stops,"sample"draws a new effect, and"zero"sets the new effect to zero. A sampled effect is one standard-normal value per new group and posterior draw, multiplied by that draw's group SD, and shared by every row in the group. Zeroing gives a typical-group reference, not a population average. Known groups keep their fitted effects. Neither choice creates a coefficient for a new level of a fixed factor.- trials
Positive integer binomial trial totals, one value or one per observation row. The default
NULLkeeps the fitted totals when you simulate the fitted rows. For new observations it uses one trial for a binary fit, and it is an error for a grouped binomial fit, which needs explicit totals. Use only with binomial models. Response columns innewdatanever supply the totals.- include_fixed
Logical. With new data,
TRUErecomputes declared fixed-radius landscape predictors fromkernel_inputs, using their original preparation means and SDs. The defaultFALSErequires those columns innewdata. Source, metric, radius, kernel, and resolution must match the fitted preparation, including itsmax_Dbuffer extent. This adds no scale parameters or uncertainty.- ...
Not used. Supplying any further argument is an error.
Value
A data frame with one row per fitted or new observation and one
column per replicate data set, named sim_1, sim_2, and so on. Values
are counts for Poisson and NB2 models, success counts out of the fitted
or supplied trial totals for binomial models (not proportions), and
response units for Gaussian models. Each column uses
one complete posterior vector, drawn at random with replacement, together
with the requested random effects.
For new data, a point_ids attribute gives the prepared landscape ID of
each row, and a new_groups attribute lists the unseen levels that were
sampled or set to zero, as in predict(). A prediction_contract
attribute (see prediction_contract) marks the result as posterior
predictive replicates that include observation noise and records the
policies for included effects. It does not establish diagnostic
eligibility or calibration.
Check the model against the data
Compare summaries of the replicate data sets with the same summaries of
the observed response. An observed value far outside the replicated range
means the model cannot reproduce that feature. Good sampling diagnostics do
not show that the observation model fits the data, and agreement on one
statistic does not establish adequacy.
vignette("v13-bayesian-scales", package = "multiScaleR") works through
such a check. To use bayesplot, convert the replicates to a matrix with one
simulated data set per row, t(as.matrix(replicated)). For a count model,
ppc_stat() with stat = function(y) mean(y == 0) checks the fraction of
zeros.
Simulate new groups jointly
Within one call, new-group effects are drawn afresh for each replicate
data set and shared by all of its rows in that group. Different new groups
are independent given the population parameters, whose joint posterior
dependence is kept. Observation noise is then drawn separately for each
row. Separate calls do not share a realization across components or
batches, so put every row that enters a joint question into one call.
Reusing a seed across predict_scales(), predict(), and simulate()
does not promise matching latent effects, because the three functions use
their random numbers differently.
To get an interval for a total, sum each replicate column first with
colSums() and then take quantiles of the sums. Adding the limits of
individual intervals overstates the range of the total.
The three prediction functions return different orientations, which
matters for joint contrasts and totals. simulate() returns observations
by replicates. predict(summary = FALSE) returns posterior draws by
observations, and predict_scales(summary = FALSE) returns a named list of
draws-by-observations matrices, one per landscape predictor.
Supply trials for binomial data
For a binary fit, new observations default to one trial. For a fit to
cbind(successes, failures), supply the actual future totals, for example
trials = rep(10L, nrow(newdata)). simulate() then returns success
counts out of those totals, while predict() returns success
probabilities whatever the number of trials.
Examples
example <- readRDS(system.file("extdata", "bayesian-annual-example.rds",
package = "multiScaleR"))
replicated <- simulate(example$fits$pooled, nsim = 20, seed = 94)
dim(replicated) # one row per original observation, one column per replicate
#> [1] 100 20
# Posterior predictive check of the fraction of zero counts
range(vapply(replicated, function(y) mean(y == 0), numeric(1)))
#> [1] 0.00 0.04
mean(example$data$count == 0) # observed fraction of zero counts
#> [1] 0.04
# These replicate counts include observation noise. Fitted means do not.
# Counts at eight future surveys, and an interval for their total
forecast <- readRDS(system.file("extdata", "bayesian-prediction-example.rds",
package = "multiScaleR"))
future <- simulate(forecast$fit, nsim = 200, seed = 803,
newdata = forecast$newdata, kernel_inputs = forecast$kernel_inputs,
row_id = "site_year", new_scale_levels = "sample",
new_response_levels = "sample")
quantile(colSums(future), c(0.025, 0.5, 0.975)) # total of the eight surveys
#> 2.5% 50% 97.5%
#> 45.925 84.500 161.025