fitdistrBayes_model: Define a User-Supplied Bayesian Distribution Model

In fitdistrBayes: Objective Bayesian Distribution Fitting

Define a User-Supplied Bayesian Distribution Model

Description

Creates a non-stateful model specification for distributions or priors not in the built-in objective-prior catalogue. The same fitdistrBayes() output and methods are used for built-in and user-supplied models.

Usage

fitdistrBayes_model(density, prior, start, name = "user-defined",
  lower = NULL, upper = NULL, fixed = NULL,
  engine = c("adaptive_metropolis", "slice", "custom"),
  sampler = NULL, independent = FALSE, engine_label = NULL,
  propriety = NULL, moments = NULL, rng = NULL,
  rng_validator = NULL, validate = NULL,
  density_is_log = NULL, prior_is_log = NULL,
  prior_style = c("auto", "scalar", "vector"),
  prior_label = "user-defined",
  prior_kernel = "user-supplied function", reference = NULL)

## S3 method for class 'fitdistrBayes_model'
print(x, ...)

Arguments

density	A density function whose first argument is the observation vector. Remaining named arguments are model parameters. An explicit logical log argument is recommended.
prior	A prior-density function accepting either named scalar parameters or a named parameter vector.
start	A finite, uniquely named numeric vector of starting values.
name	A nonempty model label used in fitted output.
lower, upper	Optional scalar, complete, or partially named parameter bounds. Missing bounds are infinite.
fixed	Optional named list of fixed model quantities.
engine	One of "adaptive_metropolis", "slice", or "custom". The slice route requires one unknown parameter.
sampler	For engine = "custom", a posterior-sampling function. See Details for its input and output contract.
independent	Whether draws returned by a custom sampler are independent. If true, MCMC convergence diagnostics are not applicable.
engine_label	Optional descriptive label for a custom sampler.
propriety	Optional user declaration or executable check of posterior propriety. It can be NULL, one logical value, one explanatory string, or a function of (x, fixed). A function returns a logical value or a list with proper and message.
moments	Optional data frame, or function of (x, fixed) returning a data frame, with columns parameter, mean_exists, variance_exists, and optionally note.
rng	Optional posterior-predictive generator. Its first argument is the requested sample size and its remaining arguments are model parameters.
rng_validator	Optional function verifying values generated by rng.
validate	Optional data-support function of (x, fixed). It returns TRUE for valid data; FALSE or an explanatory string rejects the data before posterior computation.
density_is_log, prior_is_log	Optional logical declarations for functions that do not expose a log argument.
prior_style	Whether the prior accepts named scalars, one named vector, or should be detected automatically.
prior_label, prior_kernel	Prior metadata stored in the fitted object.
reference	Optional bibliographic or methodological note stored with the specification.
x	A fitdistrBayes_model object.
...	Additional arguments, currently ignored by the print method.

Details

The adaptive Metropolis and slice engines construct the posterior kernel from density, prior, and the Jacobian implied by lower and upper. The custom engine delegates posterior simulation while retaining the package's validation, summaries, diagnostics, prediction, and pointwise log-likelihood interface.

A custom sampler receives the subset of its formal arguments matching x, log_posterior, log_posterior_unconstrained, start, fixed, lower, upper, to_unconstrained, from_unconstrained, iter, warmup, thin, chains, n_save, control, and dots. It returns either one matrix when a single chain was requested, a list of chain matrices, or a list containing a chains component and optional independent, engine, acceptance, and initialization components. Chain matrices are on the natural parameter scale, have n_save rows, and have one named column per parameter.

Propriety and moment declarations supplied through this constructor are reported explicitly as user-supplied. They are executable metadata, not a mathematical certification by the package authors. If propriety is omitted, the fit warns and records it as the user's responsibility. If moment conditions are omitted, posterior medians and quantiles remain available, but means, standard deviations, and their Monte Carlo errors are not reported.

Value

fitdistrBayes_model() returns an object of class "fitdistrBayes_model". It is a list containing the density and prior functions; named starting values and parameter bounds; fixed quantities; the selected posterior engine and optional custom sampler; user-supplied propriety, moment, support, and prediction components; and descriptive metadata. It contains no fitted values until passed to fitdistrBayes(x, distr = model).

The print method returns its input invisibly and is called for the side effect of displaying the model name, parameters, prior, engine, and availability of a propriety declaration.

Examples

# A new Laplace model with a proper, non-objective prior.
d_laplace <- function(x, location, scale, log = FALSE) {
  value <- -log(2 * scale) - abs(x - location) / scale
  if (log) value else exp(value)
}
p_laplace <- function(location, scale, log = FALSE) {
  value <- dnorm(location, 0, 5, log = TRUE) +
    dlnorm(scale, 0, 0.75, log = TRUE)
  if (log) value else exp(value)
}
r_laplace <- function(n, location, scale) {
  location + scale * ifelse(runif(n) < 0.5, -1, 1) * rexp(n)
}
laplace_model <- fitdistrBayes_model(
  d_laplace, p_laplace, start = c(location = 0, scale = 1),
  lower = c(scale = 0), name = "Laplace",
  propriety = "proper Normal--Lognormal prior for a nonconstant sample",
  moments = data.frame(
    parameter = c("location", "scale"),
    mean_exists = c(TRUE, TRUE), variance_exists = c(TRUE, TRUE),
    note = rep("finite under the stated proper prior", 2)
  ),
  rng = r_laplace,
  validate = function(x) length(x) >= 2 && diff(range(x)) > 0,
  prior_label = "Normal--Lognormal"
)
set.seed(1)
x_laplace <- r_laplace(25, location = 1, scale = 1.5)
fit_laplace <- fitdistrBayes(
  x_laplace, laplace_model, iter = 200, warmup = 80,
  chains = 2, seed = 2,
  control = list(warn_convergence = FALSE)
)
coef(fit_laplace)

fitdistrBayes documentation built on Aug. 30, 2026, 1:07 a.m.