hypothesis_provider() is the single hook through which
hypothesis_BF_model() reaches a model. Its method returns a provider, a
list of the callbacks and values that the engine needs for the statements
it plans: the parameter catalog and its entries, the draws of the tested
quantities, the random-effect quantities, and the density backends that can
evaluate them. The method for a BayesTools_fit returns the default
provider, which implements every callback with the functions of BayesTools
(parameter_catalog(), as_mixed_posteriors(), marginal_posterior(),
parameter_mixed_posterior(), JAGS_formula_coefficient_transform(), and
JAGS_formula_prior_density()). A downstream model class that wraps a
fit starts from hypothesis_provider(<its fit>) and replaces the
callbacks that differ with utils::modifyList(), so that it overrides only
what is specific to its model.
hypothesis_provider(object, ...)
# Default S3 method
hypothesis_provider(object, ...)
# S3 method for class 'BayesTools_fit'
hypothesis_provider(object, ...)A provider, a list of class BayesTools_hypothesis_provider.
A provider is a list of class
BayesTools_hypothesis_provider; the engine checks it before use. Its
elements are the following. The callbacks close over the model object.
kind"model" (default) or "marginal_means".
objectthe model object. It is hashed for the cache of plans and passed to the density backends.
fitits BayesTools_fit, from which the transforms of
formula coefficients and their prior densities are read.
capability_objectthe object the density backends receive
in available() and in their requests (default object).
build, refit_classthe name of the build in the
requests to refit a model with outdated metadata ("Refit the model with
the current <build> build."), and classes that precede
BayesTools_refit_required in those conditions.
caller, random_point_mass_advice,
transform_scaled_defaultthe name of the entry point in the
reasons of refusals (default "hypothesis_BF()"); the sentence that
ends the reason of a refused point null at a prior point mass of a
random-effect quantity; and the scale of hypothesis_quantities() when
transform_scaled is NULL.
ordinate_labelhow the messages of refusals name the
ordinate backends (default "ordinate density methods").
component_argumentthe name of the argument through which
the caller selects a value of components (default
"namespace", the argument of hypothesis_BF_model() and of the
method of hypothesis_BF() for a BayesTools_fit). The messages of
the engine that name that argument ("The 'hypothesis' argument selects
namespace = 'mu' but 'namespace' was set to 'random'.") use it; a model
class that passes the selection under another name sets it, for example
"component".
density_methodsthe names that density_method can
match, in order (default: the registered backends that are not of type
"stored").
componentsthe selection vocabulary of the namespace
argument as data: values (the accepted values, in the order of the
error message), synonyms (a named character vector, for example
c(location = "mods")), default ("auto"),
refused (a named character vector of the reasons for which a
component cannot be tested), random (the value that selects the
random-effect quantities), and advice (the sentence that follows
the message of an ambiguous statement).
metadata()a list with the catalog (a
parameter_catalog(), possibly extended with
parameter_catalog_extend(); the engine parses and resolves with it) and
the entries: a data frame with one row per tested parameter and
the columns quantity_id, parameter (the name of the tested
parameter), component (a value of components$values),
term, source, formula_parameter, role
("formula_coefficient_group" for a whole factor term, whose levels
are its member_quantity_ids), quantity, status,
fixed_value, aliases (a list column), and
member_quantity_ids (a list column). The alias rows of the catalog
of the entries carry the component as their namespace and
component.
uncovered(resolution, quantity_ids, symbol, metadata)the
refusal for resolved quantities that no entry covers: a list with
reason and either type ("target" or
"statement") or the complete condition class.
sample_parameters(parameter), mixed_posteriors(parameters,
conditional, conditional_rule, transform_scaled, n_prior_samples),
density_parameter(samples, parameter, sample_parameters),
formula_name_map(formula_parameter)the draws of a fixed
coefficient: the prior-list names whose draws are mixed (the parameter and
the owners of the fitted coordinates that its prior density combines), the
mixed posteriors (as_mixed_posteriors()), the element of the samples
that is the tested parameter, and the map of the formula coefficients to
the fitted names.
randomthe callbacks for the random-effect quantities:
select(parameter, transform_scaled) (a list with the element
spec, a list with the label and status of the
quantity, and any elements the other callbacks need),
mixed_posterior(parameter, transform_scaled, conditional, selected)
(the mixed posterior as the one-element list returned by
as_mixed_posteriors()), support(selected) (the exact bounds on
the scale requested from select(), which are those of the draws),
density_target(parameter, transform_scaled, operation) (a list with the
quantity that a density backend evaluates, its parameter_spec, and
display_transform, or the refusal of a quantity without one: its
reason, and optionally its type ("target", the
default, "method", or "fixed": the engine's refusal
BayesTools_hypothesis_<type> and its parent
BayesTools_hypothesis_unavailable) and its cause
("random_target", the default, or "original_scale"), for
which the density backend appends its classes
(refusal_classes(cause))), sd_pair(selected) (the standard deviation
of which a variance is the square, or NULL),
zero_boundary(selected) (NULL, or a list with the
statement that tests the omission of a component),
defined_share(values, selected, conditional),
defined_footnote(label, samples, posterior_defined, prior_defined),
defined_draws(values, samples, label) (the treatment of the draws
at which a quantity is undefined), and prior_draws(parameter,
selected, transform_scaled, n_samples, seed) (prior draws of a quantity
without a prior density with provenance).
point_mass_reason()NULL, or the text that replaces
the reason of a point hypothesis at a prior point mass.
full_ensemble(parameter)whether omitting
conditional tests the parameter within the full ensemble,
including the models in which it is fixed by its null component (the
engine then warns); combination_hint(plan): NULL, or text
appended to the refusal of a linear combination of the levels of such a
term.
check_plans(plans)NULL, or a function that
validates the plans of all statements of a request and stops with a
refusal.
check_density_control(density_method, density_control)NULL, or a function that checks the density_control of a
call before the control() of the density backend sees it. It
receives the name of the selected backend and the settings as supplied (a
list, possibly empty, or NULL) wherever control() is
called: on every call with an ordinate backend, and on every call that
supplies settings to another backend (for stored marginal means also
where the stored settings are normalized). It stops with the condition
that refuses the settings; its value is ignored. Without it the
built-in backends accept NULL and an empty list and refuse other
settings with the message 'density_control' is not used by
density_method = 'KDE'., and the control() of a backend
validates its own settings.
A provider of kind = "marginal_means" describes the stored marginal
means of a model instead: inference (the marginal inference with the
elements averaged and conditional), model_averaged
(logical; model-averaged point statements are tested on the conditional
draws and cannot mix with region statements), capability_object (the
fit that the backends compute ordinates from, or NULL),
select(hypothesis, parameter) (the marginal-means parameter and its
aliases that a statement names), density_method_default() and
density_control_default(density_method) (used when the arguments are
NULL), and metadata() for hypothesis_quantities().