calibrate_moments: Solve a distribution's parameters from a target mean and...

In simulab: Simulates a Wide Variety of Data Shapes, Sizes and Distributions

Solve a distribution's parameters from a target mean and variance

Description

calibrate_moments() inverts the moments of a distribution into the parameters that attain them, so a target mean and variance can be stated directly and turned into a distribution call. A one-parameter family takes mean alone, because its mean already fixes its variance; the reported variance is then the one those parameters imply.

Usage

calibrate_moments(distribution = NULL, mean = NULL, variance = NULL)

Arguments

distribution	Distribution name. calibrate_moments() with no arguments reports the distributions it can invert.
mean	Target mean, or a vector of target means.
variance	Target variance, for a two-parameter family. Omitted for a one-parameter family, whose variance its mean determines.

Details

Most inversions are closed form. For a scale family whose shape is fixed by the coefficient of variation alone – Weibull, log-logistic, Frechet, Nakagami – the shape is found by root finding and the scale then follows exactly. Two one-parameter families, chi and zero_truncated_poisson, likewise invert their mean by root finding. Some families cannot reach every pair: a Nakagami squared coefficient of variation is at most pi / 2 - 1, a Lomax with a finite variance always has one above 1, and a beta variance is below mean * (1 - mean). Those are refused rather than approximated.

Value

A base data.frame with one row per target and parameter, and columns distribution, mean, variance, parameter and value. The parameter names are those list_distributions() reports, so the result states a distribution call. For a one-parameter family the reported variance is the one the solved parameters imply rather than a target. Called with no arguments the result is instead the catalogue: one row per invertible distribution, with columns distribution, parameters and targets.

Conditions

simulab_unattainable_moments when no member of the family has the requested moments, such as a beta variance at or above mean * (1 - mean); simulab_no_moment_solution when the distribution has no implemented inversion; simulab_incompatible_lengths when mean and variance are vectors of different, non-recyclable lengths.

Examples

# The 36 distributions that can be inverted, and the targets each takes.
calibrate_moments()

# A lognormal with mean 10 and variance 25.
calibrate_moments("lognormal", mean = 10, variance = 25)

# A one-parameter family takes the mean alone and reports the variance
# that follows from it.
calibrate_moments("poisson", mean = 4)

# Targets recycle, so a sweep is one call.
calibrate_moments("gamma", mean = c(5, 10, 20), variance = 9)

simulab documentation built on Oct. 15, 2026, 5:08 p.m.