simulateNullDataset: Simulate an Empirically Calibrated Null Replicate

In bifrost: Branch-Level Inference Framework for Recognizing Optimal Shifts in Traits

Simulate an Empirically Calibrated Null Replicate

Description

Generate a single no-shift simulation replicate under a uniform Brownian motion process using the empirically calibrated covariance-generation framework. By default, each replicate uses the element-sampling operations from the published simulation code. The empirical generator is available explicitly for full-covariance draws centered on a createSimulationTemplate() object.

Usage

simulateNullDataset(
  template,
  tree_tip_count = NULL,
  seed = NULL,
  simulation_generator = c("original", "empirical"),
  covariance_df = NULL
)

Arguments

template	A bifrost_simulation_template returned by createSimulationTemplate().
tree_tip_count	Optional integer tip count for random subtree sampling. If NULL, the full empirical tree from template is used.
seed	Optional integer random seed. When supplied, the function restores the caller's previous RNG state before returning.
simulation_generator	Simulation generator to use. "original", the default, reproduces the element-sampling operations used in the published simulation code. "empirical" draws around the full fitted residual covariance. Supply exactly one supported string; explicitly supplied vectors are rejected. When omitted, "original" is used.
covariance_df	Optional integer degrees of freedom for empirical Wishart draws. It must be at least the number of response traits. The default uses the residual degrees of freedom stored in template.

Details

The default "original" generator samples marginal variance and covariance summaries and retains the published mathematical operations exactly. Under the explicit "empirical" generator, a new covariance matrix W is drawn as W \sim Wishart(\nu, S / \nu), where S is the full empirical residual covariance and \nu is covariance_df. Thus E[W] = S: empirical integration is retained on average while individual replicates vary.

For templates calibrated from richer global models, the empirical fitted mean structure is added back to the simulated residual process before the downstream intercept-only search is run on the regenerated response block. The returned trait_data therefore contains only the simulated response variables, even when the global calibration model included predictors. This is the lower-level replicate generator used by runFalsePositiveSimulationStudy(); use that wrapper for replicated false-positive simulation workflows.

Value

A list of class bifrost_simulation_replicate_null containing the sampled tree, a single-regime baseline tree, the simulated response matrix, a response-only trait_data object used for downstream model fitting, and the generated covariance matrix, generator metadata, resolved covariance degrees of freedom, and covariance diagnostics.

See Also

createSimulationTemplate(), simulateShiftedDataset(), runFalsePositiveSimulationStudy()

Examples

set.seed(1)
tr <- ape::rtree(12)
X <- matrix(rnorm(12 * 2), ncol = 2)
rownames(X) <- tr$tip.label
tmpl <- createSimulationTemplate(tr, X, formula = "trait_data ~ 1", method = "LL")

sim_null <- simulateNullDataset(tmpl, tree_tip_count = 10, seed = 2)
dim(sim_null$trait_data)

bifrost documentation built on Nov. 5, 2026, 9:07 a.m.